FastAPI API文档定制指南：4 步做出带品牌色的 Swagger 与 ReDoc 界面

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

做 FastAPI API文档定制，核心是三件事：让浏览器能读到你写的 CSS、用参数调好主题、在断网环境下把资源自托管到本地。FastAPI 自带 Swagger UI 和 ReDoc 两套界面，下面按 4 步把它们调成你的品牌风格，全程只改配置和样式文件，不动业务代码。

先看效果：默认界面和品牌色差在哪

同一个项目，默认文档页和加了自定义样式之后，差别肉眼可见：Swagger UI 的蓝色按钮、ReDoc 的浅色调，往往和你产品的 VI 对不上。

ReDoc 默认是左侧目录、右侧详情的浅色布局，状态码自带绿红底色。如果你希望文档页和产品主色一致，从下面三步开始改。

第 1 步｜把 static 目录挂上，CSS 才有入口

这一步解决"你写的样式文件，浏览器怎么拿到"。FastAPI 的StaticFiles负责这件事：

from fastapi import FastAPI from fastapi.staticfiles import StaticFiles app = FastAPI() # 把磁盘上的 static 目录映射到 /static 路径 app.mount("/static", StaticFiles(directory="static"), name="static")

先建一个static文件夹，把custom.css放进去，启动服务后访问/static/custom.css能看到文件内容，说明这一步成了。两个小提醒：目录必须真实存在，否则启动就报错；静态资源走的是"子应用"，它的文件不会出现在 OpenAPI Schema 里，这正是你想要的。

第 2 步｜主题参数先调，CSS 后补

这一步解决"不动一行 CSS，先改多少东西"。swagger_ui_parameters把键值对原样传给 Swagger UI，其中syntaxHighlight.theme控制代码块配色：

app = FastAPI( swagger_ui_parameters={ "syntaxHighlight.theme": "nord" # 代码高亮主题 } )

常用取值：arta（深色）、monokai（经典暗色）、nord（冷色调）、obsidian（深色）。改完记得强制刷新页面看看效果——浏览器会缓存旧的界面资源。这一步见效快、风险低，所以建议放在写 CSS 之前做。

第 3 步｜断网 / 内网环境的资源自托管

这一步解决"内网部署时文档页直接白屏"。原因很简单：默认界面从公网 CDN 拉 JS 和 CSS，断网时加载不到，页面就只剩标题。

做法三步走：1）创建应用时关掉自动文档；2）把swagger-ui-bundle.js、swagger-ui.css、redoc.standalone.js从官方文档页的 HTML 源码里另存到static目录；3）用fastapi.openapi.docs里的两个函数自己生成文档页，让css_url、js_url指向本地资源：

from fastapi import FastAPI from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html app = FastAPI(docs_url=None, redoc_url=None) # 关闭自动文档，改用自己的 app.mount("/static", StaticFiles(directory="static"), name="static") @app.get("/docs", include_in_schema=False) async def swagger_ui(): return get_swagger_ui_html( openapi_url=app.openapi_url, title=app.title, swagger_js_url="/static/swagger-ui-bundle.js", # 指向本地 JS swagger_css_url="/static/swagger-ui.css", # 指向本地 CSS swagger_ui_parameters={"syntaxHighlight.theme": "nord"}, ) @app.get("/redoc", include_in_schema=False) async def redoc_ui(): return get_redoc_html( openapi_url=app.openapi_url, title=app.title, redoc_js_url="/static/redoc.standalone.js", # 指向本地 JS )

这里有个容易绕晕的点：swagger_css_url不是FastAPI(...)构造函数的参数，它属于get_swagger_ui_html；ReDoc 侧同理，ReDoc 只有一个redoc_js_url，样式基本都编译进 JS 里了。验证方法：断开外网访问/docs，能正常渲染就算成了。更多细节可参考仓库内的静态文件自托管文档。

进阶｜3 处 CSS 细节让文档更专业

这一步解决"结构能用了，怎么更像品牌"。在custom.css里做三件事：按状态码配色、按钮加质感、标题贴品牌色。前两件最能提升可读性：

/* 2xx 成功：浅绿底 + 绿色左边框，一眼可辨 */ .response-col_status-200 { background-color: rgba(46, 204, 113, 0.1); border-left: 4px solid #2ecc71; } /* 4xx 客户端错误：浅红底 + 红色左边框 */ .response-col_status-400, .response-col_status-422 { background-color: rgba(231, 76, 60, 0.1); border-left: 4px solid #e74c3c; } /* Try it out 按钮：加过渡和悬停位移 */ .swagger-ui .btn.execute { transition: all 0.2s ease; } .swagger-ui .btn.execute:hover { transform: translateY(-2px); }

状态码列会多出一列柔和的色块，"Try it out"悬停时微微上浮，点击调试接口的欲望都强一点。细节改完，把custom.css通过第 3 步的方式加载进去（或让swagger_css_url指向一个合并后的文件），再刷新页面确认。

容易踩的坑与优化建议

• 缓存坑：改 CSS 没生效，多半是浏览器缓存。先Ctrl + Shift + R强制刷新，再怀疑代码。
• 路径坑：StaticFiles(directory="static")相对启动目录解析，用uvicorn main:app时从项目根目录启动最省心；directory不存在会直接启动失败。
• 版本坑：自托管的文件要锁死版本号，CDN 上@5这类标签可能悄悄升级，本地文件不会，两边行为不一致最难查。
• 体积坑：下载官方压缩版文件；样式超过两百行就上 Sass / Less，编译后再压缩输出，别把开发中的源文件直接上线。
• 边界坑：app.mount挂的是子应用，/static下的文件不会出现在/docs的接口列表里，别指望靠它们提供 API。

改完记得强制刷新页面确认样式真的生效。API 文档页是外部用户接触你服务的第一块界面，配色、按钮和代码高亮统一成品牌风格之后，文档就不再是"附带的说明书"，而是产品体验的一部分。

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi