mkdocs-swagger-ui-tag

What it is and what it does

This plugin extends MkDocs by allowing you to embed interactive Swagger UI viewers directly into your documentation pages using a simple HTML tag. Instead of linking to external API documentation or hosting Swagger UI separately, you add a `<swagger-ui>` tag pointing to an OpenAPI specification file—either a remote URL or a local file in your docs folder—and the plugin converts it into an embedded iframe with full Swagger UI functionality.

The plugin handles all the heavy lifting: it copies Swagger UI's JavaScript and CSS assets into your site's static directories, generates the necessary iframe HTML, and supports multiple Swagger UIs on the same page. It integrates with Material for MkDocs' dark mode, lets you configure Swagger UI behavior through plugin options (like operation expansion, syntax highlighting theme, and Try It Out settings), and supports OAuth2 flows. All assets are served locally rather than from a CDN, making it suitable for intranet deployments.

Use it for:

• Embed API documentation directly in MkDocs sites alongside other guides and tutorials without maintaining separate Swagger UI hosting.
• Display multiple OpenAPI specs in one documentation site with a selector bar to switch between them.
• Support OAuth2-protected API testing in embedded Swagger UI with configurable redirect URLs.
• Serve Swagger UI entirely from local assets in air-gapped or intranet environments without CDN access.
• Customize Swagger UI appearance and behavior per-page through tag attributes while keeping global defaults in mkdocs.yml.

Worth the install?

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

A MkDocs plugin that embeds Swagger UI directly into documentation pages to display OpenAPI specifications, supporting both remote URLs and local files.

Yes. The plugin is actively maintained, has no known vulnerabilities, installs with minimal friction, and solves a real problem for teams documenting APIs in MkDocs. It's particularly valuable if you want to avoid hosting Swagger UI separately or need to serve API docs in restricted network environments.

Install

mkdocs-swagger-ui-tag on PyPI

pip install mkdocs-swagger-ui-tag

uv add mkdocs-swagger-ui-tag

poetry add mkdocs-swagger-ui-tag

Installing mkdocs-swagger-ui-tag

Before you install

Low friction install with a single runtime dependency (beautifulsoup4). Active maintenance with a recent release (35 days ago) and steady repository activity.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install mkdocs-swagger-ui-tag

Add to mkdocs.yml:
plugins:
  - swagger-ui-tag

In markdown:
<swagger-ui src="https://petstore.swagger.io/v2/swagger.json"/>

Requires MkDocs to be installed and a valid mkdocs.yml configuration file in your project.

Verify before relying

• Whether the plugin requires Node.js or npm to be installed separately for Swagger UI dist files
• Compatibility with MkDocs versions beyond the Python version support range

Package facts

Evidence: mkdocs_swagger_ui_tag-0.8.1-py3-none-any.whl

Keywords: mkdocs, openapi, plugin, swagger-ui

Tags

More Text Processing packages