{"id":8322,"library":"mkdocs-swagger-ui-tag","title":"MkDocs Swagger UI Tag","description":"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.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/blueswen/mkdocs-swagger-ui-tag","tags":["mkdocs","swagger","openapi","documentation","plugin","ui"],"install":[{"cmd":"pip install mkdocs-swagger-ui-tag","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for any MkDocs plugin.","package":"mkdocs","optional":false},{"reason":"Used for HTML parsing and manipulation within the plugin; requires >=4.13.3 as of current version.","package":"beautifulsoup4","optional":false}],"imports":[],"quickstart":{"code":"site_name: My API Docs\ntheme: material\n\nplugins:\n  - swagger-ui-tag\n\nnav:\n  - Home: index.md\n  - API Reference: api.md\n\n# api.md content example:\n# # My API Documentation\n#\n# <swagger-ui src=\"./openapi.yaml\" />\n","lang":"yaml","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially major `swagger-ui-dist` updates (e.g., v5.0.0 in `mkdocs-swagger-ui-tag 0.6.2`)."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Swagger UI not loading or appearing blank in the documentation page."},{"fix":"Run `pip install mkdocs-swagger-ui-tag` to install the plugin. Ensure your Python environment is active where MkDocs is also installed.","cause":"The `mkdocs-swagger-ui-tag` Python package has not been installed in your environment.","error":"ERROR   -  Config value 'plugins': 'swagger-ui-tag' is not installed."},{"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.","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.","error":"Dark mode styling of Swagger UI does not match the MkDocs Material theme or appears inconsistent."}]}