Install the plugin using
pip install mkdocs-render-swagger-plugin.
Add the following lines to your mkdocs.yml:
plugins: - render_swagger
Place an OpenAPI json in the same folder as the the
!!swagger <filename>!! at the appropriate location inside the markdown file.
Referencing external json
You may reference an external OpenAPI json using the following syntax:
Explicit declaration of the Swagger JS library
You can explicitly specify the swagger-ui css and js dependencies if you wish to not use the unpkg CDN.
Keep in mind, the filename has to be
swagger-ui.css for the CSS and
swagger-ui-bundle.js for the JS.
To specify this use
extra_css in your mkdocs.yaml:
Contributing & Developing Locally
After downloading and extracting the
.tar.gz, install this package locally using
pip and the
pip install --editable .
You'll then have the
render-swagger package available to use in Mkdocs and
pip will point the dependency to this folder. You are then able to run the docs using
mkdocs serve. Make sure you restart the process between code changes as the plugin is loaded on startup.
MkDocs plugins and Swagger api
The Render Swagger MkDocs plugin uses a set of extensions and plugin APIs that MkDocs and Swagger UI supports. You can find more info about MkDocks plugins and Swagger UI on the official website of MkDocks and SwaggerUI.
Disclaimer: This plugin is unofficial, and is not sponsored, owned or endorsed by mkdocs, swagger, or any other 3rd party.
Credits to @aviramha for starting this project.