Widdershins
Widdershins converts API definition files into documentation inputs for rendering pipelines.
What Widdershins is
Widdershins converts API definition files into documentation inputs for rendering pipelines. It accepts OpenAPI 3.x and 2.0, API Blueprint, AsyncAPI and Semoasa formats. Its main output is Markdown compatible with Slate and ReSlate; it can also produce HTML directly or use ReSpec format. The project describes it as a conversion stage for tools including Slate, ReSlate, Shins and ReSpec. Code samples can be customized with language tabs, and httpsnippet can generate samples. Included templates may be edited or overridden to change the output. Installation is available globally with npm install -g widdershins, or by cloning the repository and running npm i. Node.js programs can call its convert function, which returns a Promise. Widdershins is free, MIT-licensed software for API, Linux and self-hosted use. Schema examples default to depth 10, while referenced request-body schemas are not expanded unless they contain an inline schema.
Good
- Supports OpenAPI, AsyncAPI and other inputs
- Produces Markdown, HTML or ReSpec output
- Customizable code samples and templates
- Works with several documentation renderers
- Free MIT-licensed software
Watch out
- Schema examples default to depth 10
- Referenced request bodies are not expanded by default
- Requires npm installation or repository setup
Who it suits
It suits developers building self-hosted API documentation pipelines around supported definition formats. Teams using Slate, ReSlate, Shins or ReSpec can use its conversion and template options.
Verdict
Widdershins is a flexible conversion step for generating documentation from API definitions. Its renderer integrations and customization options are useful, with schema expansion defaults worth checking before processing complex specifications.
Plans and prices
From Widdershins's own pricing page, checked 4 Oct 2026.
| Plan | Price | What it gives you |
|---|---|---|
| Widdershins | Free | Open source MIT-licensed software · install via npm or clone the repository |
The facts
Each one read from Widdershins's own pages, with the date it was checked.
What it does
- API use
- Widdershins can be called from Node.js using its convert function, which returns a Promise.checked 4 Oct 2026
- Code samples
- It supports customizable code samples, including language tabs, and can use httpsnippet to generate samples.checked 4 Oct 2026
- Input formats
- The project describes support for OpenAPI 3.x, OpenAPI 2.0, API Blueprint, AsyncAPI, and Semoasa inputs.checked 4 Oct 2026
- Install
- The project can be installed globally with npm install -g widdershins or installed by cloning the repository and running npm i.checked 4 Oct 2026
- Integrations
- The README describes using Widdershins with Slate, ReSlate, Shins, and ReSpec renderers.checked 4 Oct 2026
- License
- The repository identifies its license as MIT.checked 4 Oct 2026
- Limits
- Schema examples default to a maximum depth of 10, and referenced request body schemas are not expanded by default unless they have an inline schema.checked 4 Oct 2026
- Output formats
- Widdershins can produce Markdown and can also output HTML directly or use ReSpec format.checked 4 Oct 2026
- Pipeline
- It is intended as a stage in an API documentation pipeline, converting API definitions for a renderer.checked 4 Oct 2026
- Purpose
- Widdershins converts OpenAPI, Swagger, AsyncAPI, and Semoasa definitions into Markdown compatible with Slate and ReSlate.checked 4 Oct 2026
- Security
- The README documents generated Authorization headers in OpenAPI code samples and provides an option to customize the API key value.checked 4 Oct 2026
- Templates
- Users can customize output by editing or overriding the included templates.checked 4 Oct 2026
Alternatives to Widdershins
- 1
Scalar
Free planOpen sourceWebAPILinuxmacOS8.4From $150 a month - 2
Redocly
WebAPIExtension7.0From $10 a month - 3
Sphinx
Free planWebAPILinuxmacOS7.0Free plan - 4
Asciidoctor
Free planWebAPIExtensionLinux6.9Free plan - 5
JSON Schema for Humans
Free planLinuxmacOSSelf-hostedWindows6.5Free plan - 6
StepShot
Free planmacOS6.5CN¥269 one-time