OpenAPI Specs support for MKDocs-mateiral

[eo33]

Context

Hey there! 👋 I'm looking for a new tool to document the public-facing API of my app. Most documentation tools make it easy to display OpenAPI specs beautifully, you just point them to your OpenAPI specs file (either JSON or YAML), and the tool takes care of the rest. It would be nice if MKDocs had a built-in plugin or library to render OpenAPI docs as well.

Description

A native plugin / library to MKDocs-materials that allows devs to render OpenAPI specifications (can be in JSON or YAML format). The plugin / library would convert the OpenAPI spec and generate a Markdown file used for displaying the API documentation within the MKDocs-material site.

Related links

• Requesting a change

Use Cases

From an author's perspective, the process would be simple and intuitive. After installing the plugin, the author can simply point to their OpenAPI spec file (in JSON or YAML format) within the MKDocs configuration, and the tool would automatically generate a well-structured, easy-to-navigate representation of their API documentation. Authors wouldn’t need to manually format or structure the API documentation, saving time and effort while ensuring consistency.

Visuals

No response

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for suggesting. As I understand, there are several alternatives already as listed in the catalog:

• MkDocsOAD
• MkDocs Swagger Plugin

Converting this to a discussion, as this is considered out of scope for us.