FastAPI 配置 Swagger UIswagger_ui_parameters 参数全解与源码实现剖析【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文基于 FastAPI 官方文档《Configure Swagger UI》讲解如何通过swagger_ui_parameters参数定制/docs交互式文档页面关闭或调整语法高亮、切换配色主题、覆盖内置默认参数并结合fastapi/openapi/docs.py与fastapi/applications.py的源码实现剖析这些 Python 字典是如何被合并、序列化为 JSON 并安全地注入到 Swagger UI 页面中的。读完后你可以直接复制示例代码定制自己的 API 文档外观并理解每个配置项在底层的作用机制。swagger_ui_parameters 是什么Swagger UI 本身暴露了一整套 配置参数如布局、深链接、扩展显示等。FastAPI 通过一个统一入口把它们开放给了 Python 用户swagger_ui_parameters。有两种使用方式在创建FastAPI()应用对象时传入在自行调用get_swagger_ui_html()函数时传入。swagger_ui_parameters接收一个字典字典内容会直接透传给 Swagger UI。FastAPI 在生成页面 HTML 时会把这些配置转换为JSON因为 Swagger UI 是 JavaScript 应用它需要 JSON 对象而非 Python 字面量。在 FastAPI 主类 中该参数被声明为dict[str, Any] | None默认值为None应用启动时保存为实例属性self.swagger_ui_parametersapplications.py随后在注册/docs路由时透传给get_swagger_ui_html()applications.py# fastapi/applications.py节选 async def swagger_ui_html(req: Request) - HTMLResponse: root_path req.scope.get(root_path, ).rstrip(/) openapi_url root_path self.openapi_url oauth2_redirect_url self.swagger_ui_oauth2_redirect_url if oauth2_redirect_url: oauth2_redirect_url root_path oauth2_redirect_url return get_swagger_ui_html( openapi_urlopenapi_url, titlef{self.title} - Swagger UI, oauth2_redirect_urloauth2_redirect_url, init_oauthself.swagger_ui_init_oauth, swagger_ui_parametersself.swagger_ui_parameters, )从源码结构看FastAPI(swagger_ui_parameters...)与直接调用get_swagger_ui_html(swagger_ui_parameters...)走的是同一条数据通路效果完全等价。关闭语法高亮例如你可以关闭 Swagger UI 中的语法高亮。在不修改任何设置时语法高亮默认是开启的见上文第一张截图字符串呈绿色。通过把syntaxHighlight设置为False即可关闭完整示例如下对应 示例源码from fastapi import FastAPI app FastAPI(swagger_ui_parameters{syntaxHighlight: False}) app.get(/users/{username}) async def read_user(username: str): return {message: fHello {username}}运行后访问/docsExample Value 面板中的 JSON 将不再着色见第二张截图。切换语法高亮主题同样的思路你可以通过带点号的键syntaxHighlight.theme设置语法高亮的主题注意中间那个点它是 Swagger UI 配置路径的写法from fastapi import FastAPI app FastAPI(swagger_ui_parameters{syntaxHighlight: {theme: obsidian}}) app.get(/users/{username}) async def read_user(username: str): return {message: fHello {username}}对应 示例源码。该配置会改变语法高亮的配色方案上图中第三张截图即为切换到obsidian主题后的效果字符串变为橙色。覆盖 FastAPI 的默认 Swagger UI 参数FastAPI 内置了一批适合大多数使用场景的默认配置参数它们定义在 fastapi/openapi/docs.py 的swagger_ui_default_parameters中swagger_ui_default_parameters { dom_id: #swagger-ui, layout: BaseLayout, deepLinking: True, showExtensions: True, showCommonExtensions: True, }各参数含义默认参数默认值作用dom_id#swagger-uiSwagger UI 挂载到的 HTML 元素 ID必须与页面中的div idswagger-ui一致layoutBaseLayout页面布局控制器控制接口列表、详情、侧边栏的排布方式deepLinkingTrue开启深链接访问某个接口时 URL 会带上锚点可分享精确到单个操作showExtensionsTrue在 UI 中展示 OpenAPI 的扩展字段x- 前缀showCommonExtensionsTrue同时展示所有层级不仅是 operation 级的扩展字段你可以用swagger_ui_parameters中的同名键覆盖其中任意一项。例如禁用deepLinking对应 示例源码from fastapi import FastAPI app FastAPI(swagger_ui_parameters{deepLinking: False}) app.get(/users/{username}) async def read_user(username: str): return {message: fHello {username}}默认值与自定义值的合并规则覆盖行为发生在get_swagger_ui_html()内部docs.py 的实现是“先拷贝默认值、再用你的值覆盖”current_swagger_ui_parameters swagger_ui_default_parameters.copy() if swagger_ui_parameters: current_swagger_ui_parameters.update(swagger_ui_parameters)这说明你只需提供想改动的键未提供的键会继续使用默认值不会丢失dom_id等关键项.copy()保证每次生成页面时默认字典本身不会被污染多次请求互不影响。随后合并后的字典会被逐项序列化为 JSON 并拼接进页面的script块docs.pyfor key, value in current_swagger_ui_parameters.items(): html f{_html_safe_json(key)}: {_html_safe_json(jsonable_encoder(value))},\n这里jsonable_encoder负责把 Python 值字符串、布尔、嵌套字典等转换为合法 JSON这正是文档所说“FastAPI 会把配置转换为 JSON 以兼容 JavaScript”的实现位置。嵌入script标签时的 HTML 安全转义由于这些配置最终是嵌进 HTML 的script标签里FastAPI 还专门做了防注入处理。_html_safe_json 会把序列化结果中的、、分别替换为\u003c、\u003e、\u0026def _html_safe_json(value: Any) - str: Serialize a value to JSON with HTML special characters escaped. This prevents injection when the JSON is embedded inside a script tag. return ( json.dumps(value) .replace(, \\u003c) .replace(, \\u003e) .replace(, \\u0026) )仓库中的测试 tests/test_swagger_ui_escape.py 专门验证了这一行为当swagger_ui_parameters传入包含img srcx onerroralert(1)的值时断言原始字符串不会出现在生成的 HTML 中而是被转义为\u003cimg形式。这从侧面说明swagger_ui_parameters中允许嵌套字典、列表等任意可 JSON 化的 Python 值如前文{syntaxHighlight: {theme: obsidian}}且特殊字符会被安全处理。此外tests/test_local_docs.py 验证了get_swagger_ui_html()生成的页面中包含正确的 Swagger UI JS/CSS/favicon 资源引用可作为检查自定义配置是否生效的最小用例参考。其他可用的 Swagger UI 参数除文档示例的syntaxHighlight、deepLinking外Swagger UI 支持的其余配置项如dom_id、layout、requestSnippets、filter、tagsSorter等都可以用同样的方式传入。完整清单请以 Swagger UI 官方配置文档为准FastAPI 侧不做限制——字典里任何可 JSON 序列化的键值对都会透传。仅限 JavaScript 的配置项如何处理Swagger UI 还允许一些仅 JavaScript的配置例如 JavaScript 函数对象。FastAPI 生成的页面本身就写死了一组presets见 docs.pypresets: [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset ]这些是JavaScript 对象对SwaggerUIBundle全局变量的引用不是字符串因此无法从 Python 代码直接传过去——swagger_ui_parameters里放函数或对象引用是没有意义的。如果确实需要用到这类仅限 JavaScript 的配置文档给出的方案是不要只传参数而是整体覆盖 Swagger UI 的 path operation手动编写所需的 JavaScript。也就是说自己注册一个/docs路由在路由函数里返回HTMLResponse完全接管 HTML 模板可以参照get_swagger_ui_html()生成的 HTML 结构自行拼装。这也是 FastAPI 提供的“逃生舱”swagger_ui_parameters覆盖 90% 的场景剩下 10% 的 JavaScript-only 需求通过覆写路由解决。小结定制/docs外观只需给FastAPI()或get_swagger_ui_html()传swagger_ui_parameters字典值为可直接透传给 Swagger UI 的 JSON 兼容配置点号键如syntaxHighlight.theme用于设置嵌套配置FastAPI 的默认参数集dom_id、layout、deepLinking、showExtensions、showCommonExtensions可在 fastapi/openapi/docs.py 中查看传入同名键即可覆盖未传的键保持默认参数合并、JSON 序列化与script内嵌转义的实现均在get_swagger_ui_html()中可结合 tests/test_swagger_ui_escape.py 验证行为无法序列化的 JavaScript-only 配置如presets请通过覆写整个 Swagger UI 路由的方式手动编写 JavaScript。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FastAPI 配置 Swagger UI：swagger_ui_parameters 参数全解与源码实现剖析
FastAPI 配置 Swagger UIswagger_ui_parameters 参数全解与源码实现剖析【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文基于 FastAPI 官方文档《Configure Swagger UI》讲解如何通过swagger_ui_parameters参数定制/docs交互式文档页面关闭或调整语法高亮、切换配色主题、覆盖内置默认参数并结合fastapi/openapi/docs.py与fastapi/applications.py的源码实现剖析这些 Python 字典是如何被合并、序列化为 JSON 并安全地注入到 Swagger UI 页面中的。读完后你可以直接复制示例代码定制自己的 API 文档外观并理解每个配置项在底层的作用机制。swagger_ui_parameters 是什么Swagger UI 本身暴露了一整套 配置参数如布局、深链接、扩展显示等。FastAPI 通过一个统一入口把它们开放给了 Python 用户swagger_ui_parameters。有两种使用方式在创建FastAPI()应用对象时传入在自行调用get_swagger_ui_html()函数时传入。swagger_ui_parameters接收一个字典字典内容会直接透传给 Swagger UI。FastAPI 在生成页面 HTML 时会把这些配置转换为JSON因为 Swagger UI 是 JavaScript 应用它需要 JSON 对象而非 Python 字面量。在 FastAPI 主类 中该参数被声明为dict[str, Any] | None默认值为None应用启动时保存为实例属性self.swagger_ui_parametersapplications.py随后在注册/docs路由时透传给get_swagger_ui_html()applications.py# fastapi/applications.py节选 async def swagger_ui_html(req: Request) - HTMLResponse: root_path req.scope.get(root_path, ).rstrip(/) openapi_url root_path self.openapi_url oauth2_redirect_url self.swagger_ui_oauth2_redirect_url if oauth2_redirect_url: oauth2_redirect_url root_path oauth2_redirect_url return get_swagger_ui_html( openapi_urlopenapi_url, titlef{self.title} - Swagger UI, oauth2_redirect_urloauth2_redirect_url, init_oauthself.swagger_ui_init_oauth, swagger_ui_parametersself.swagger_ui_parameters, )从源码结构看FastAPI(swagger_ui_parameters...)与直接调用get_swagger_ui_html(swagger_ui_parameters...)走的是同一条数据通路效果完全等价。关闭语法高亮例如你可以关闭 Swagger UI 中的语法高亮。在不修改任何设置时语法高亮默认是开启的见上文第一张截图字符串呈绿色。通过把syntaxHighlight设置为False即可关闭完整示例如下对应 示例源码from fastapi import FastAPI app FastAPI(swagger_ui_parameters{syntaxHighlight: False}) app.get(/users/{username}) async def read_user(username: str): return {message: fHello {username}}运行后访问/docsExample Value 面板中的 JSON 将不再着色见第二张截图。切换语法高亮主题同样的思路你可以通过带点号的键syntaxHighlight.theme设置语法高亮的主题注意中间那个点它是 Swagger UI 配置路径的写法from fastapi import FastAPI app FastAPI(swagger_ui_parameters{syntaxHighlight: {theme: obsidian}}) app.get(/users/{username}) async def read_user(username: str): return {message: fHello {username}}对应 示例源码。该配置会改变语法高亮的配色方案上图中第三张截图即为切换到obsidian主题后的效果字符串变为橙色。覆盖 FastAPI 的默认 Swagger UI 参数FastAPI 内置了一批适合大多数使用场景的默认配置参数它们定义在 fastapi/openapi/docs.py 的swagger_ui_default_parameters中swagger_ui_default_parameters { dom_id: #swagger-ui, layout: BaseLayout, deepLinking: True, showExtensions: True, showCommonExtensions: True, }各参数含义默认参数默认值作用dom_id#swagger-uiSwagger UI 挂载到的 HTML 元素 ID必须与页面中的div idswagger-ui一致layoutBaseLayout页面布局控制器控制接口列表、详情、侧边栏的排布方式deepLinkingTrue开启深链接访问某个接口时 URL 会带上锚点可分享精确到单个操作showExtensionsTrue在 UI 中展示 OpenAPI 的扩展字段x- 前缀showCommonExtensionsTrue同时展示所有层级不仅是 operation 级的扩展字段你可以用swagger_ui_parameters中的同名键覆盖其中任意一项。例如禁用deepLinking对应 示例源码from fastapi import FastAPI app FastAPI(swagger_ui_parameters{deepLinking: False}) app.get(/users/{username}) async def read_user(username: str): return {message: fHello {username}}默认值与自定义值的合并规则覆盖行为发生在get_swagger_ui_html()内部docs.py 的实现是“先拷贝默认值、再用你的值覆盖”current_swagger_ui_parameters swagger_ui_default_parameters.copy() if swagger_ui_parameters: current_swagger_ui_parameters.update(swagger_ui_parameters)这说明你只需提供想改动的键未提供的键会继续使用默认值不会丢失dom_id等关键项.copy()保证每次生成页面时默认字典本身不会被污染多次请求互不影响。随后合并后的字典会被逐项序列化为 JSON 并拼接进页面的script块docs.pyfor key, value in current_swagger_ui_parameters.items(): html f{_html_safe_json(key)}: {_html_safe_json(jsonable_encoder(value))},\n这里jsonable_encoder负责把 Python 值字符串、布尔、嵌套字典等转换为合法 JSON这正是文档所说“FastAPI 会把配置转换为 JSON 以兼容 JavaScript”的实现位置。嵌入script标签时的 HTML 安全转义由于这些配置最终是嵌进 HTML 的script标签里FastAPI 还专门做了防注入处理。_html_safe_json 会把序列化结果中的、、分别替换为\u003c、\u003e、\u0026def _html_safe_json(value: Any) - str: Serialize a value to JSON with HTML special characters escaped. This prevents injection when the JSON is embedded inside a script tag. return ( json.dumps(value) .replace(, \\u003c) .replace(, \\u003e) .replace(, \\u0026) )仓库中的测试 tests/test_swagger_ui_escape.py 专门验证了这一行为当swagger_ui_parameters传入包含img srcx onerroralert(1)的值时断言原始字符串不会出现在生成的 HTML 中而是被转义为\u003cimg形式。这从侧面说明swagger_ui_parameters中允许嵌套字典、列表等任意可 JSON 化的 Python 值如前文{syntaxHighlight: {theme: obsidian}}且特殊字符会被安全处理。此外tests/test_local_docs.py 验证了get_swagger_ui_html()生成的页面中包含正确的 Swagger UI JS/CSS/favicon 资源引用可作为检查自定义配置是否生效的最小用例参考。其他可用的 Swagger UI 参数除文档示例的syntaxHighlight、deepLinking外Swagger UI 支持的其余配置项如dom_id、layout、requestSnippets、filter、tagsSorter等都可以用同样的方式传入。完整清单请以 Swagger UI 官方配置文档为准FastAPI 侧不做限制——字典里任何可 JSON 序列化的键值对都会透传。仅限 JavaScript 的配置项如何处理Swagger UI 还允许一些仅 JavaScript的配置例如 JavaScript 函数对象。FastAPI 生成的页面本身就写死了一组presets见 docs.pypresets: [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset ]这些是JavaScript 对象对SwaggerUIBundle全局变量的引用不是字符串因此无法从 Python 代码直接传过去——swagger_ui_parameters里放函数或对象引用是没有意义的。如果确实需要用到这类仅限 JavaScript 的配置文档给出的方案是不要只传参数而是整体覆盖 Swagger UI 的 path operation手动编写所需的 JavaScript。也就是说自己注册一个/docs路由在路由函数里返回HTMLResponse完全接管 HTML 模板可以参照get_swagger_ui_html()生成的 HTML 结构自行拼装。这也是 FastAPI 提供的“逃生舱”swagger_ui_parameters覆盖 90% 的场景剩下 10% 的 JavaScript-only 需求通过覆写路由解决。小结定制/docs外观只需给FastAPI()或get_swagger_ui_html()传swagger_ui_parameters字典值为可直接透传给 Swagger UI 的 JSON 兼容配置点号键如syntaxHighlight.theme用于设置嵌套配置FastAPI 的默认参数集dom_id、layout、deepLinking、showExtensions、showCommonExtensions可在 fastapi/openapi/docs.py 中查看传入同名键即可覆盖未传的键保持默认参数合并、JSON 序列化与script内嵌转义的实现均在get_swagger_ui_html()中可结合 tests/test_swagger_ui_escape.py 验证行为无法序列化的 JavaScript-only 配置如presets请通过覆写整个 Swagger UI 路由的方式手动编写 JavaScript。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考