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.
pip install mkdocs-swagger-ui-tagNo compatibility data collected yet for this library.
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.
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.
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.
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.
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.
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.
Run `pip install mkdocs-swagger-ui-tag` to install the plugin. Ensure your Python environment is active where MkDocs is also installed.
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.