mkdocs-render-swagger-plugin

This is the Mkdocs plugin for rendering swagger & openapi schemas using Swagger UI. It is written in Python.

Usage

Install the plugin using pip install mkdocs-render-swagger-plugin.

Add the following lines to your mkdocs.yml:

plugins:
  - render_swagger

Example

Here's an example (courtesy of Scarf) of how the plugin renders swagger.

Referencing a local json

Place an OpenAPI json file in the same folder as the .md file.

Enter !!swagger FILENAME!! at the appropriate location inside the markdown file.

If you wish to reference any files on the filesytem (security risk), make sure you enable allow_arbitrary_locations in the config (mkdocs.yml) like so:

plugins:
  - render_swagger:
      allow_arbitrary_locations : true

Referencing an external json

You may reference an external OpenAPI json using the following syntax: !!swagger-http URL!!.

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.

To specify this use javascript and css in your mkdocs.yaml:

plugins:
  - render_swagger:
      javascript: assets/js/swagger-ui-bundle.js
      css: assets/css/swagger-ui.css

Contributing & Developing Locally

After downloading and extracting the .tar.gz, install this package locally using pip and the --editable flag:

pip install --editable ".[dev]"

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 MkDocs plugins and Swagger UI on the official website of MkDocs and SwaggerUI.

The input OpenAPI files processed by the plugin should conform to the OpenAPI specification. It is generated by a few projects such as pydantic, FastAPI and others.