MkDocs Swagger UI Tag

0.8.0 · active · verified Thu Apr 16

mkdocs-swagger-ui-tag is an active MkDocs plugin that allows developers to embed interactive Swagger UI (OpenAPI) documentation directly into their MkDocs-generated pages. It supports both online OpenAPI Specification files via URL and static files stored within the `docs` directory, offering features like multiple Swagger UIs on a single page, and synchronized dark mode with themes like Material for MkDocs. The plugin handles all its JavaScript and CSS dependencies locally, making it suitable for environments without direct CDN access. It is currently at version 0.8.0.

Common errors

```
Swagger UI not loading or appearing blank in the documentation page.
```
cause The `swagger-ui-tag` plugin might not be enabled in `mkdocs.yml`, the OpenAPI specification file path in the `<swagger-ui>` tag is incorrect, or the OpenAPI file itself is invalid.

fix 1. Ensure `swagger-ui-tag` is listed under `plugins:` in your `mkdocs.yml` file. 2. Verify that the `src` attribute in your `<swagger-ui src="...">` tag points to a valid and accessible OpenAPI (YAML/JSON) file relative to your `docs` directory. 3. Check the browser's developer console for any loading errors or JavaScript issues related to the Swagger UI iframe.
```
ERROR   -  Config value 'plugins': 'swagger-ui-tag' is not installed.
```
cause The `mkdocs-swagger-ui-tag` Python package has not been installed in your environment.

fix Run `pip install mkdocs-swagger-ui-tag` to install the plugin. Ensure your Python environment is active where MkDocs is also installed.
```
Dark mode styling of Swagger UI does not match the MkDocs Material theme or appears inconsistent.
```
cause Prior to v0.8.0, custom dark mode solutions might have been used or specific `swagger-ui-dist` versions behaved differently. The plugin now uses Swagger UI's built-in dark mode which might override previous custom styles.

fix Upgrade to `mkdocs-swagger-ui-tag` version 0.8.0 or higher, as it includes built-in dark mode synchronization. Ensure your `mkdocs-material` theme is up-to-date. If issues persist, review the plugin's documentation for relevant dark mode configuration options and check for any conflicting custom CSS.

Warnings

breaking Version 0.8.0 switched to Swagger UI's built-in dark mode and added support for deactivating browser cache for OpenAPI files. This may alter the appearance of dark mode in your documentation if you had custom styling or relied on previous dark mode implementations, and could affect caching behavior.
Fix: Review your `mkdocs.yml` configuration and custom CSS for dark mode settings. Test your documentation thoroughly after upgrading to ensure the Swagger UI renders as expected and caching behaves correctly. Refer to the plugin's documentation for specific configuration options related to dark mode and caching if issues arise.
gotcha Swagger UI instances might not display properly or fully load when navigating to pages via the sidebar while running `mkdocs serve`, but often work correctly after building the static site with `mkdocs build`.
Fix: If experiencing display issues during development with `mkdocs serve`, try rebuilding the site (`mkdocs build`) and serving the static output with a simple HTTP server (e.g., `python -m http.server`). Always verify the final output with `mkdocs build` for production deployment.
gotcha The plugin frequently updates its embedded `swagger-ui-dist` library, sometimes with significant version jumps. While this keeps the UI current, it can introduce subtle visual or behavioral changes in the Swagger UI itself, which are outside the control of the `mkdocs-swagger-ui-tag` plugin's configuration.
Fix: Be aware that the underlying Swagger UI's behavior or appearance might change with plugin updates. Review the `mkdocs-swagger-ui-tag` changelog for `swagger-ui-dist` version bumps and test your documentation to catch any unexpected changes. Utilize the plugin's configuration options in `mkdocs.yml` or tag attributes to mitigate unwanted UI behaviors.
gotcha Swagger UI configuration options can be applied globally in `mkdocs.yml` or locally using attributes on the `<swagger-ui>` tag. Local tag attributes will override global plugin settings.
Fix: Clearly define where you intend to configure Swagger UI options. Use global settings in `mkdocs.yml` for consistent behavior across all instances, and only use local tag attributes for page-specific overrides. Document your choices to avoid confusion and unexpected behavior.

Install

pip install mkdocs-swagger-ui-tag Install latest version

Quickstart

To quickly integrate `mkdocs-swagger-ui-tag`, first, create an `mkdocs.yml` file and enable the plugin under the `plugins` section. Then, within any Markdown file (e.g., `api.md`), use the `<swagger-ui>` custom tag, providing the `src` attribute with the path to your OpenAPI specification file (e.g., `openapi.yaml`) which should be located within your `docs` directory. Finally, run `mkdocs serve` to see your documentation with the embedded Swagger UI.

site_name: My API Docs
theme: material

plugins:
  - swagger-ui-tag

nav:
  - Home: index.md
  - API Reference: api.md

# api.md content example:
# # My API Documentation
#
# <swagger-ui src="./openapi.yaml" />

view raw JSON →