MkDocs Render Swagger Plugin

0.1.2 verified Mon Apr 27 auth: no python

MkDocs plugin for rendering Swagger & OpenAPI specification files in documentation pages. Current version 0.1.2, supporting Swagger-UI v5. Released on PyPI, actively maintained.

pip install mkdocs-render-swagger-plugin

Common errors

error Plugin 'render-swagger' not found ↓

cause mkdocs.yml uses hyphenated name instead of underscore.

fix

Use 'render_swagger' in plugins list, matching the plugin's entry point.

error No module named 'mkdocs_render_swagger_plugin' ↓

cause Package not installed or installed in wrong environment.

fix

Run 'pip install mkdocs-render-swagger-plugin' and activate the correct Python environment.

Warnings

breaking Version 0.1.0 bumped Swagger-UI to major version 5, which may break customizations relying on internal CSS or JS selectors. ↓

fix Review Swagger-UI 5 migration guide; update any custom assets or styling.

gotcha The plugin uses the package name 'mkdocs-render-swagger-plugin' but the entry point in mkdocs.yml is 'render_swagger' (with underscores). ↓

fix In mkdocs.yml, use 'plugins: [render_swagger]' or the full import path as configured.

Imports

SwaggerUI
```
from mkdocs_render_swagger_plugin import SwaggerUI
```
The package's main class is SwaggerUI, used internally; no direct user import typically required.

Quickstart

Add the plugin to mkdocs.yml, then use the :swagger: tag in markdown files to embed an OpenAPI spec.

# In mkdocs.yml:
# plugins:
#   - render_swagger

# In a markdown page:
# :swagger: path/to/openapi.yaml

# Example usage with env variable:
# :swagger: https://petstore.swagger.io/v2/swagger.json