FastAPI API 文档美化实战：4 步把默认 Swagger UI 换成你的品牌风格

FastAPI API 文档美化实战4 步把默认 Swagger UI 换成你的品牌风格【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapiFastAPI 的 API 文档界面开箱即用可默认 Swagger UI 千篇一律所有项目的顶栏、按钮、配色长得一模一样放进交付演示里很难体现品牌。下面这套 FastAPI 文档美化方案让你不动业务代码、不改路由用 4 步就能把/docs和/redoc换成你自己的视觉风格顺带解决内网离线访问的问题。这张是出厂状态蓝色GET条、灰白响应区、默认字体。你要做的是覆盖它、而不是重写它。5 分钟见效3 行代码给 Swagger UI 换上第一块品牌皮肤想让改动立刻可见别急着上静态文件。FastAPI()的swagger_ui_parameters会把字典原样转成 JSON 喂给 Swagger UI而 Swagger UI 恰好认customCss这个键——一段 CSS 字符串追加在默认样式之后不会把界面弄成白板。from fastapi import FastAPI app FastAPI(swagger_ui_parameters{ customCss: ( .swagger-ui .topbar { background: #2c3e50; } .swagger-ui .info h2 { color: #3498db; } ) })⚡ 起服务刷新/docs顶栏变深、API 标题变蓝第一个定制效果就有了。注意选择器都带了.swagger-ui前缀——这是让它盖住默认值、又不污染页面的关键。一键切换语法高亮主题改一个字典键皮肤只改了几处颜色代码块的高亮还是默认的暗色块。高亮主题走同一个字典键名用点号表示层级改一个键就行。app FastAPI(swagger_ui_parameters{ syntaxHighlight: {theme: obsidian}, deepLinking: True, })obsidian、monokai、nord、arta都能用不想要高亮就写syntaxHighlight: False。deepLinking这类默认值也能在这里覆盖改完 URL 会带上#锚点方便同事直接跳到某个接口。替换品牌色与交互按钮从内联 CSS 到独立文件规则一多塞在字典里就不好读了。把 CSS 挪进文件再用 Python 读进来传给customCss既保留追加行为又能像普通样式表一样维护。from pathlib import Path from fastapi import FastAPI brand_css Path(static/styles.css).read_text() app FastAPI(swagger_ui_parameters{customCss: brand_css})文件里只写有代表性的规则其余靠注释提示扩展点/* 顶栏换成深色品牌色 */ .swagger-ui .topbar { background: #2c3e50; } /* 响应按钮悬停上移 2px过渡 0.3s */ .swagger-ui .btn.execute { background: #3498db; transition: all 0.3s ease; } .swagger-ui .btn.execute:hover { background: #2980b9; transform: translateY(-2px); } /* 4xx/422 响应加红色左边条思路同上用 .response-col_status-4xx 选择器 */填参数、点 Execute 的这套交互态是你最想让访客记住的部分——按钮、输入框、Curl 代码块的配色都在customCss里改得到。离线/内网自托管让文档不依赖任何 CDN 前面几步样式都生效了但 Swagger UI 的 JS/CSS 默认走 jsDelivr。断网或内网部署时页面直接空掉。解法是先关默认文档再自己挂载并重新接上。下载并挂载三个文件把swagger-ui-bundle.js、swagger-ui.css、redoc.standalone.js放进static/浏览器右键另存为链接即可然后挂载目录from fastapi import FastAPI from fastapi.staticfiles import StaticFiles app FastAPI(docs_urlNone, redoc_urlNone) # 关掉默认,避免仍走 CDN app.mount(/static, StaticFiles(directorystatic), namestatic)重接 /docs 与 /redoc复用框架内部的 HTML 生成函数把资源 URL 指回本地。from fastapi.openapi.docs import get_swagger_ui_html, get_redoc_html app.get(/docs, include_in_schemaFalse) async def custom_docs(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titleapp.title, swagger_js_url/static/swagger-ui-bundle.js, swagger_css_url/static/swagger-ui.css, ) app.get(/redoc, include_in_schemaFalse) async def custom_redoc(): return get_redoc_html( openapi_urlapp.openapi_url, titleapp.title, redoc_js_url/static/redoc.standalone.js, with_google_fontsFalse, # 内网也关掉 Google Fonts )with_google_fontsFalse是内网部署最容易漏的一行ReDoc 默认还要去 Google 拉字体。本地起服务后用curl http://127.0.0.1:8000/static/swagger-ui.css | head -c 60确认文件真的吐出来了再刷新/docs此时断开网络它照样能开。踩坑清单5 个最容易翻车的点把swagger_css_url指向自己的 CSS结果界面变白板。这个参数是替换默认样式表不是追加想要叠加品牌皮肤用customCss。改了 CSS 浏览器没反应。多半是缓存给文件加版本号?v2或换个文件名再刷一次。选择器太裸样式盖不住默认值。一定带.swagger-ui前缀必要时加到.swagger-ui .topbar这种两级别只写h2。/static撞上了业务路由。换个更具体的前缀如/assets或确认没有同名接口被它吞掉。离线页能开但字体还是外网请求。除了 JS/CSS别忘了with_google_fontsFalse否则 ReDoc 仍会连 Google。完整参数对照可查仓库里的 how-to/configure-swagger-ui 与 how-to/custom-docs-ui-assets教程源码在 docs_src/custom_docs_ui/。走到这里默认 Swagger UI 已经能变成你品牌的一部分而且内网、断网都不掉链子。再往下把customCss交给 Sass/Less 做主题变量、抽成一套可复用的设计 token多项目共享同一份视觉就是自然的下一步。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考