In this walkthrough tutorial, you'll learn how to convert OpenAPI 3.0 definitions to MarkDown with Widdershins CLI.

The reasons to parse an OpenAPI document and convert it to MarkDown could be diverse. In our case, we wanted to render the OpenAPI documentation fully integrated with Sphinx, one of our go-to site generators for documentation projects.

So if you've already written an OpenAPI document and are curious about how you can turn it into MarkDown, let's dive in.

Prerequisites

• Have a valid OpenAPI document.
• Have NodeJS 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 Jekyll, Docusaurus, or Sphinx.

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

Conclusion

We hope this was a helpful introduction to transform your OpenAPI 3.0 definitions to Markdown using the Widdershins CLI. Now, you can integrate your API documentation into various static site generators for improved accessibility and presentation.

As a nex step, consider automating the Markdown generation process to keep your documentation up-to-date with changes to your OpenAPI file. We also helped our clients to postprocess the MarkDown file and dividing it into multiple files to have smoother navigation between the contents.

If you found this tutorial helpful, subscribe to our newsletter for more insightful content. Happy documenting!