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

The reasons to parse an OpenAPI document and convert it to MarkDown could be diverse. In my case, I wanted to render beautiful documentation fully integrated with Sphinx, my go-to static site generator for documentation projects of choice.

So if you have already written an OpenAPI file and you would like to get an idea of how you can turn it into MarkDown, this article might be of interest to you.

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 will be using 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 and 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 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. Replace openapi.yaml with the path to your OpenAPI file in YAML or JSON.

widdershins openapi.yaml -o openapi.md

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

Customizing the output with flags

Widdershins comes with other built-in options to configure how the output looks like. 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, I'm 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 how the MarkDown output looks like. However, you can't achieve the level of customization desired by just tweaking Widdershins CLI's options. In this case, what I do is to 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
  1. 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
  1. Edit main.dot with your favourite 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.
  1. 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

I hope this was a helpful introduction to transform your OpenAPI to MarkDown.

Next, you could code a script to automatically generate MarkDown docs every time the original OpenAPI file receives an update. In my case, I'm also postprocessing the MarkDown file and dividing it into multiple files to have smoother navigation between the contents.

Please let me know if you succeed at @dgarcia360 and share the article if it helped you out!