Version can be a random string. You can use major.minor.patch (as in semantic versioning), or an arbitrary format like 1.0-beta or 2016.11.15. Description can be multiline and supports GitHub Flavored Markdown for rich text representation. Info also supports other fields for contact information, license and other details. Reference: Info Object. Variable description is optional, but useful to have and supports Markdown for rich text formatting. Common use cases for server templating: Specifying multiple protocols (such as HTTP vs HTTPS). SaaS (hosted) applications where each customer has their own subdomain.

• Description: the description of your API, in OpenAPI and the automatic API docs UIs. Version: the version of your API, e.g. Useful for example if you had a previous version of the application, also using OpenAPI. To set them, use the parameters title, description, and version.
• Markdown extension for PlantUML and Nikola. Renders PlantUML files from Nikola. JSDoc plugin to use PlantUML inside javascript documentation. Simple tool to turn a swagger api spec into a uml class diagram. Convert OpenAPI specifications to PlantUML diagrams. Generate UML Diagrams for Given Swagger Definition. Use it with LyX.
• This page shows how to take full advantage of special documentation capabilities in OpenAPI like markdown syntax or example objects. The Documentation Fields Almost every object in the OpenAPI Specification accepts a description field which can provide additional information for developers, beyond what can be automatically generated from the.

You can customize several metadata configurations in your FastAPI application.

Title, description, and version¶

You can set the:

• Title: used as your API's title/name, in OpenAPI and the automatic API docs UIs.
• Description: the description of your API, in OpenAPI and the automatic API docs UIs.
• Version: the version of your API, e.g. v2 or 2.5.0.
  • Useful for example if you had a previous version of the application, also using OpenAPI.

To set them, use the parameters title, description, and version:

With this configuration, the automatic API docs would look like:

Metadata for tags¶

You can also add additional metadata for the different tags used to group your path operations with the parameter openapi_tags.

It takes a list containing one dictionary for each tag.

Each dictionary can contain:

• name (required): a str with the same tag name you use in the tags parameter in your path operations and APIRouters.
• description: a str with a short description for the tag. It can have Markdown and will be shown in the docs UI.
• externalDocs: a dict describing external documentation with:
  • description: a str with a short description for the external docs.
  • url (required): a str with the URL for the external documentation.

Create metadata for tags¶

Let's try that in an example with tags for users and items.

Create metadata for your tags and pass it to the openapi_tags parameter:

Notice that you can use Markdown inside of the descriptions, for example 'login' will be shown in bold (login) and 'fancy' will be shown in italics (fancy).

Tip

You don't have to add metadata for all the tags that you use.

Use your tags¶

Use the tags parameter with your path operations (and APIRouters) to assign them to different tags:

Info

Read more about tags in Path Operation Configuration.

Check the docs¶

Now, if you check the docs, they will show all the additional metadata:

Order of tags¶

The order of each tag metadata dictionary also defines the order shown in the docs UI.

For example, even though users would go after items in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.

OpenAPI URL¶

By default, the OpenAPI schema is served at /openapi.json.

But you can configure it with the parameter openapi_url.

For example, to set it to be served at /api/v1/openapi.json:

If you want to disable the OpenAPI schema completely you can set openapi_url=None, that will also disable the documentation user interfaces that use it.

Docs URLs¶

You can configure the two documentation user interfaces included:

• Swagger UI: served at /docs.
  • You can set its URL with the parameter docs_url.
  • You can disable it by setting docs_url=None.
• ReDoc: served at /redoc.
  • You can set its URL with the parameter redoc_url.
  • You can disable it by setting redoc_url=None.

For example, to set Swagger UI to be served at /documentation and disable ReDoc:

In this walkthrough tutorial, you will learn how to work with Widdershins CLI to convert OpenAPI 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.

Swagger Specification

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.

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

Customizing the output with flags

Openapi Description Markdown Function

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:

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.

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

3. 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

Openapi 3 Description Markdown

Print

Conditional

Iteration

Open Api Description Markdown Tool

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

Swagger 2.0 Specification

Swagger Api Spec

Conclusion

Open Api Description Markdown Tutorial

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!