MkDocs Swagger UI Tag

一个MkDocs插件，支持在页面中添加Swagger UI。

在线演示，使用Material for MkDocs。

功能

1. 从URL或文档中的静态文件中获取OpenAPI规范文件
2. 所有依赖项都使用由插件处理的静态文件，而不是来自CDN，特别适合那些部署在内网中的文档
3. 同一页面上可以有多个Swagger UI
4. 与Material for MkDocs同步的暗黑模式
5. 通过插件选项和标签属性配置Swagger UI配置
6. 在单个Swagger UI中支持多个OAS，带有顶部栏选择器
7. 支持Swagger UI的initOAuth方法

依赖

1. Python包
   1. beautifulsoup4>=4.11.1
2. Swagger UI dist JavaScript文件和CSS文件
   1. swagger-ui-dist==5.17.3

用法

1. 从PyPI安装插件

   pip install mkdocs-swagger-ui-tag
   

2. 将swagger-ui-tag插件添加到mkdocs.yml的插件部分

   plugins:
      - swagger-ui-tag
   

3. 在Markdown中添加swagger-ui标签以包含Swagger UI

   <swagger-ui src="https://petstore.swagger.io/v2/swagger.json"/>
   

   

4. 您可以通过mkdocs.yml中的选项自定义插件，有关更多信息请参阅选项

   plugins:
      - swagger-ui-tag:
           background: White
           docExpansion: none
           filter: ""
           syntaxHighlightTheme: monokai
           tryItOutEnabled: ['get', 'post']
   

   选项	类型	描述
   background	字符串	默认: "". Swagger UI iframe body背景属性值。您可以使用任何CSS值作为背景，例如 "#74b9ff" 或 "Gainsboro" 或 "" 为无。
   docExpansion	字符串	默认值："list"。控制操作和标签的默认展开设置。可以是“list”（仅展开标签）、“full”（展开标签和操作）或“none”（不展开任何内容）。
   filter	字符串或布尔值	默认值：False。如果设置，则启用过滤。顶部栏将显示一个编辑框，您可以使用它来过滤显示的标签操作。可以是布尔值以启用或禁用，或字符串，在这种情况下，将使用该字符串作为过滤表达式启用过滤。过滤是区分大小写的，匹配标签内的过滤表达式。
   syntaxHighlightTheme	字符串	默认值："agate"。要使用的Highlight.js语法着色主题。可以是“agate”、“arta”、“monokai”、“nord”、“obsidian”或“tomorrow-night”。
   tryItOutEnabled	布尔值	默认值：False。此设置确定“尝试它”部分的默认可编辑性，包括参数或主体。
   oauth2RedirectUrl	字符串	默认值：与mkdocs.yml中的site_url相关联的绝对URL“/assets/swagger-ui/oauth2-redirect.html”，或者在无site_url的站点上的文档根路径，例如“https://blueswen.github.io/mkdocs-swagger-ui-tag/assets/swagger-ui/oauth2-redirect.html”。OAuth重定向URL。
   supportedSubmitMethods	数组	默认值：所有HTTP方法。数组=["get", "put", "post", "delete", "options", "head", "patch", "trace"]。具有“尝试它”功能启用的HTTP方法列表。空数组将禁用所有操作的“尝试它”功能。这不会过滤显示的操作。
   validatorUrl	字符串	默认值：“https://validator.swagger.io/validator”。默认情况下，Swagger UI会尝试将规范与swagger.io的在线验证器进行验证，在多个OAS Swagger UI中。您可以使用此参数设置不同的验证器URL，例如本地部署的验证器（Validator Badge）。将其设置为“none”以禁用验证。

工作原理

1. 将Swagger UI脚本文件复制到site/assets/javascripts/目录，CSS文件复制到site/assets/stylesheets/目录，并将默认的Oauth2重定向HTML（default Oauth2 redirect html）复制到site/assets/swagger-ui/目录。
2. 搜索所有swagger-ui标签，然后将它们转换为iframe标签，并使用给定的OpenAPI规范src路径和选项生成iframe目标HTML。

许可证

本项目采用MIT许可证 - 详细信息请参阅LICENSE.md文件。

参考

1. Amoenus Swagger Dark Theme：暗模式CSS的来源