mkdocs-render-swagger-plugin

这是使用Swagger UI渲染swagger & openapi模式的Mkdocs插件。它是用Python编写的。

用法

使用pip install mkdocs-render-swagger-plugin安装插件。

在您的mkdocs.yml中添加以下行

plugins:
  - render_swagger

示例

这里有一个示例（由Scarf提供），展示了插件如何渲染swagger。

引用本地json

将OpenAPI json文件放置在.md文件相同的文件夹中。

在markdown文件的适当位置输入!!swagger FILENAME!!。

如果您希望引用文件系统上的任何文件（存在安全风险），请确保在配置（mkdocs.yml）中启用allow_arbitrary_locations，如下所示

plugins:
  - render_swagger:
      allow_arbitrary_locations : true

引用外部json

您可以使用以下语法引用外部OpenAPI json：!!swagger-http URL!!。

显式声明Swagger JS库

如果您不想使用unpkg CDN，可以显式指定swagger-ui css和js依赖项。

要在mkdocs.yaml中指定此内容，请使用javascript和css。

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

贡献 & 本地开发

下载并解压.tar.gz后，使用pip和--editable标志在本地安装此包

pip install --editable ".[dev]"

您将拥有可用于Mkdocs的render-swagger包，并且pip将此依赖项指向此文件夹。然后，您可以使用mkdocs serve运行文档。确保在代码更改之间重启进程，因为插件在启动时加载。

MkDocs插件和Swagger API

Render Swagger MkDocs 插件使用了一套 MkDocs 和 Swagger UI 支持的扩展和插件 API。您可以在 MkDocs 和 SwaggerUI 的官方网站上找到有关 MkDocs 插件和 Swagger UI 的更多信息。

该插件处理的输入 OpenAPI 文件应符合 OpenAPI 规范。它由一些项目生成，如 pydantic、FastAPI 等。

免责声明：此插件为非官方插件，不受 mkdocs、swagger 或任何其他第三方赞助、拥有或支持。
感谢 @aviramha 开发此项目。