Widdershins

What Widdershins is

Widdershins converts API definitions into documentation output for a renderer in an API documentation pipeline. It accepts OpenAPI 3.x and 2.0, API Blueprint, AsyncAPI, and Semoasa inputs. It can produce Markdown compatible with Slate and ReSlate, HTML directly, or ReSpec format; integrations described by the project include Slate, ReSlate, Shins, and ReSpec. Code samples can be customized, including language tabs, and httpsnippet can generate samples. Users can adapt output by editing or overriding the included templates. Widdershins can be installed globally with npm install -g widdershins or from a cloned repository using npm i. Node.js applications can call its convert function, which returns a Promise. The project is free, open-source, and MIT-licensed. Schema examples have a default maximum depth of 10, and referenced request body schemas are not expanded by default unless they include an inline schema. OpenAPI code samples can generate Authorization headers, and an option allows customization of the API key value.

Who it suits

Widdershins suits developers building API documentation pipelines who need to convert supported definitions for a renderer. It can also suit teams that want to customize templates and code samples.

Limits

Schema examples default to a maximum depth of 10. Referenced request body schemas are not expanded by default unless they include an inline schema.

Getting started

1. Install globally with npm install -g widdershins, or clone the repository and run npm i.
2. Provide an OpenAPI, API Blueprint, AsyncAPI, or Semoasa definition.
3. Convert the definition to Markdown, HTML, or ReSpec format.
4. Use the generated content with a renderer such as Slate, ReSlate, Shins, or ReSpec.
5. For Node.js use, call the convert function, which returns a Promise.

Verdict

Widdershins offers several API definition inputs and renderer-oriented outputs, with templates and samples users can adapt. Its default schema expansion behavior may matter when preparing documentation.