How to convert an OpenAPI document to MarkDown

Use Widdershins to parse OpenAPI 3.0 specs into Markdown for static site generators

You’ve written an OpenAPI spec. Now you need it as Markdown to integrate with your documentation site built on Sphinx, Docusaurus or Mkdocs.

Widdershins converts OpenAPI to Markdown. Here’s how to use it.

Prerequisites

• Have a valid OpenAPI document.

• Have Node.js installed on your computer.

• Have basic command-line knowledge.

What’s Widdershins?

Widdershins is the open-source command-line tool we’ll use to convert the OpenAPI document to MarkDown. By default, Widdershins outputs MarkDown compatible with renderers such as Slate, ReSlate, and Shins.

Thanks to its customizable template system, we can customize the output to make it compatible with other static site generators such as Sphinx, Docusaurus or Mkdocs.

Installing Widdershins

Widdershins can be installed with NPM. In the command prompt, run the following command:

npm install -g widdershins

After the installation has been completed, you can verify Widdershins installation by running widdershins --version in the command prompt.

Parsing OpenAPI to MarkDown

Once Widdershins is installed, run the following command in the console prompt:

widdershins openapi.yaml -o openapi.md

Replace openapi.yaml with the path to your OpenAPI file in YAML or JSON.

The command stores the resulting MarkDown file as openapi.md.

Customizing the output with flags

Widdershins comes with other built-in options to configure the output. For example, the option omitHeader removes the YAML front-matter in the generated Markdown file.

👉 Check out the complete list of available options in the official docs.

In this example, we’re running the command from the previous step with the new option omitHeader:

widdershins openapi.yaml -o openapi.md --omitHeader

Using custom-defined templates

Suppose you want to change the output’s format, but you can’t achieve the level of customization you are looking for by just tweaking Widdershins CLI’s options. In this case, what we did is override the template Widdershins uses with a custom-defined template.

Here’s how:

1. Create a new directory named .widdershins. Inside, create a second folder named templates.

mkdir -p .widdershins/templates
cd .widdershins/templates

2. Copy the contents from the file main.dot in the folder you just created.

curl https://raw.githubusercontent.com/Mermade/widdershins/master/templates/openapi3/main.dot > main.dot

3. Edit main.dot with your favorite code editor. The template engine Widdershins uses is doT.js. This enables you to access any variable from the OpenAPI description, even vendor extensions or nested fields.

From my experience, getting started with the template engine could be tricky. Here’s a cheatsheet with the delimiters I’ve been using more to render and iterate through variables:

Evaluate

{{ var enums = []; }} // Executes the JavaScript code between the curly braces.

Print

{{=a}} // Renders the contents of the variable a
{{=a.b}}  // Renders the contents of the nested variable a.b

Conditional

{{? a }} hello {{?}} // If a is true, prints “hello”.
{{? !a }} hello {{?}} // If a is false, prints “hello”.
{{? a || b }} hello {{?}} // If a or b is true, prints “hello”.
{{? a && b }} hello {{?}} // If a and b is true, prints “hello”.

Iteration

{{~ alist:a}} {{= a }} {{~}}  // Iterates throught alist and prints every element.

4. Run the Widdershins CLI. In this case, add the option -u with the path to .widdershins/templates:

widdershins openapi.yaml -o openapi.md -u ./widdershins/templates

Next steps

• Automate the conversion. Add Widdershins to your CI/CD pipeline so Markdown updates automatically when the OpenAPI spec changes.

• Split into multiple files. Large API specs generate massive Markdown files. Post-process the output to split by endpoint or resource for better navigation.

• Integrate with your site generator. Configure your static site generator (Sphinx, Docusaurus, Mkdocs) to handle the generated Markdown with proper styling and navigation.

---

I write about documentation systems, developer experience, and technical writing. Get new posts by email