--- id: mkdocs-render-swagger-plugin version: "0.1.2" license: unclear license_treatment: permissive maintenance: dormant --- # mkdocs-render-swagger-plugin — MKDocs plugin for rendering swagger & openapi files. License: permissive · Maintenance: dormant · Downloads: 149.2K/mo ## What it is and what it does mkdocs-render-swagger-plugin is an MkDocs plugin that embeds interactive Swagger UI documentation directly into your MkDocs site by rendering OpenAPI and Swagger JSON schemas. It works by inserting special markup tags into your markdown files—either `!!swagger FILENAME!!` for local JSON files or `!!swagger-http URL!!` for external schemas—which the plugin then converts into fully interactive API documentation at build time. The plugin uses Swagger UI from a CDN by default but allows you to specify custom JavaScript and CSS assets if needed. It integrates with the MkDocs plugin system and respects the OpenAPI specification standard, making it compatible with schemas generated by tools like FastAPI and Pydantic. However, the project is currently dormant with no active maintenance, so it may not receive updates for compatibility issues with newer mkdocs or OpenAPI versions. Use it for: - Embed interactive API documentation directly in your project's MkDocs site without maintaining separate documentation portals. - Display OpenAPI schemas generated by FastAPI or similar frameworks as part of your technical documentation. - Reference multiple API specifications from different sources (local files or external URLs) within a single documentation site. - Customize Swagger UI appearance by providing your own CSS and JavaScript assets instead of relying on the CDN. ## Worth the install? AI-flagged interpretation of the facts above — verify before relying. Renders Swagger and OpenAPI schemas as interactive documentation within MkDocs sites using Swagger UI, supporting both local JSON files and external URLs. Yes, if you are building MkDocs documentation and want to embed interactive OpenAPI/Swagger schemas with minimal setup. The low install friction and permissive license make it straightforward to add. However, be aware that maintenance is dormant—if you encounter issues or need support for newer OpenAPI versions, you may need to fork or patch the plugin yourself. Suitable for stable, self-contained documentation projects. ## Install pip install mkdocs-render-swagger-plugin uv add mkdocs-render-swagger-plugin poetry add mkdocs-render-swagger-plugin ## Installing mkdocs-render-swagger-plugin Before you install: Low friction install as a pure Python wheel with a single runtime dependency on mkdocs. Maintenance is dormant—last release was 2024-05-26, with no commits since 2024-09-23, so expect no active bug fixes or feature updates. License in practice: MIT license (permissive) means you can use, modify, and distribute this plugin freely in commercial and open-source projects with minimal restrictions. Quickstart: pip install mkdocs-render-swagger-plugin Add to mkdocs.yml: plugins: - render_swagger In your markdown file: !!swagger openapi.json!! or !!swagger-http https://example.com/openapi.json!! Requires Python 3.8 or later and an existing mkdocs project; OpenAPI files must conform to the OpenAPI specification. Verify before relying: - Whether the plugin works with recent mkdocs versions given the dormant maintenance status. - Whether Swagger UI CDN dependencies (unpkg) remain stable and accessible. - Support for OpenAPI 3.1 or only earlier versions of the specification. ## Package facts - License: not declared (permissive) - Python support: supports_current - Install friction: low - Maintenance: dormant - Downloads: 149.2K/month (top 15,000 on PyPI) - Known vulnerabilities: none known ## Tags mkdocs openapi documentation, swagger ui mkdocs plugin, render openapi schemas, api documentation mkdocs, swagger json viewer mkdocs, openapi spec rendering, api-documentation, openapi, mkdocs-plugin [View on SkillFed](https://skillfed.io/packages/mkdocs-render-swagger-plugin) · [View on PyPI](https://pypi.org/project/mkdocs-render-swagger-plugin/)