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/fastapi

FastAPI 的 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_url=None, redoc_url=None) # 关掉默认,避免仍走 CDN app.mount("/static", StaticFiles(directory="static"), name="static")

重接 /docs 与 /redoc：复用框架内部的 HTML 生成函数，把资源 URL 指回本地。

from fastapi.openapi.docs import get_swagger_ui_html, get_redoc_html @app.get("/docs", include_in_schema=False) async def custom_docs(): return get_swagger_ui_html( openapi_url=app.openapi_url, title=app.title, swagger_js_url="/static/swagger-ui-bundle.js", swagger_css_url="/static/swagger-ui.css", ) @app.get("/redoc", include_in_schema=False) async def custom_redoc(): return get_redoc_html( openapi_url=app.openapi_url, title=app.title, redoc_js_url="/static/redoc.standalone.js", with_google_fonts=False, # 内网也关掉 Google Fonts )

with_google_fonts=False是内网部署最容易漏的一行：ReDoc 默认还要去 Google 拉字体。本地起服务后，用curl http://127.0.0.1:8000/static/swagger-ui.css | head -c 60确认文件真的吐出来了，再刷新/docs，此时断开网络它照样能开。

踩坑清单：5 个最容易翻车的点

1. 把swagger_css_url指向自己的 CSS，结果界面变白板。这个参数是替换默认样式表，不是追加；想要叠加品牌皮肤，用customCss。
2. 改了 CSS 浏览器没反应。多半是缓存，给文件加版本号（?v=2）或换个文件名再刷一次。
3. 选择器太裸，样式盖不住默认值。一定带.swagger-ui前缀，必要时加到.swagger-ui .topbar这种两级，别只写h2。
4. /static撞上了业务路由。换个更具体的前缀（如/assets），或确认没有同名接口被它吞掉。
5. 离线页能开，但字体还是外网请求。除了 JS/CSS，别忘了with_google_fonts=False，否则 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