mkdocs-render-swagger-plugin

What it is and what it does

mkdocs-render-swagger-plugin is an MkDocs plugin that embeds interactive Swagger UI documentation directly into your MkDocs site by rendering OpenAPI and Swagger JSON schemas. It works by inserting special markup tags into your markdown files—either `!!swagger FILENAME!!` for local JSON files or `!!swagger-http URL!!` for external schemas—which the plugin then converts into fully interactive API documentation at build time.

The plugin uses Swagger UI from a CDN by default but allows you to specify custom JavaScript and CSS assets if needed. It integrates with the MkDocs plugin system and respects the OpenAPI specification standard, making it compatible with schemas generated by tools like FastAPI and Pydantic. However, the project is currently dormant with no active maintenance, so it may not receive updates for compatibility issues with newer mkdocs or OpenAPI versions.

Use it for:

• Embed interactive API documentation directly in your project's MkDocs site without maintaining separate documentation portals.
• Display OpenAPI schemas generated by FastAPI or similar frameworks as part of your technical documentation.
• Reference multiple API specifications from different sources (local files or external URLs) within a single documentation site.
• Customize Swagger UI appearance by providing your own CSS and JavaScript assets instead of relying on the CDN.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Renders Swagger and OpenAPI schemas as interactive documentation within MkDocs sites using Swagger UI, supporting both local JSON files and external URLs.

Yes, if you are building MkDocs documentation and want to embed interactive OpenAPI/Swagger schemas with minimal setup. The low install friction and permissive license make it straightforward to add. However, be aware that maintenance is dormant—if you encounter issues or need support for newer OpenAPI versions, you may need to fork or patch the plugin yourself. Suitable for stable, self-contained documentation projects.

Install

mkdocs-render-swagger-plugin on PyPI

pip install mkdocs-render-swagger-plugin

uv add mkdocs-render-swagger-plugin

poetry add mkdocs-render-swagger-plugin

Installing mkdocs-render-swagger-plugin

Before you install

Low friction install as a pure Python wheel with a single runtime dependency on mkdocs. Maintenance is dormant—last release was 2024-05-26, with no commits since 2024-09-23, so expect no active bug fixes or feature updates.

License in practice

MIT license (permissive) means you can use, modify, and distribute this plugin freely in commercial and open-source projects with minimal restrictions.

Quickstart

pip install mkdocs-render-swagger-plugin

Add to mkdocs.yml:
plugins:
  - render_swagger

In your markdown file:
!!swagger openapi.json!!
or
!!swagger-http https://example.com/openapi.json!!

Requires Python 3.8 or later and an existing mkdocs project; OpenAPI files must conform to the OpenAPI specification.

Verify before relying

• Whether the plugin works with recent mkdocs versions given the dormant maintenance status.
• Whether Swagger UI CDN dependencies (unpkg) remain stable and accessible.
• Support for OpenAPI 3.1 or only earlier versions of the specification.

Package facts

Evidence: mkdocs_render_swagger_plugin-0.1.2-py3-none-any.whl

Tags

More Documentation packages