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(directorystatic), namestatic)先建一个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_urlNone, redoc_urlNone) # 关闭自动文档改用自己的 app.mount(/static, StaticFiles(directorystatic), namestatic) app.get(/docs, include_in_schemaFalse) async def swagger_ui(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titleapp.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_schemaFalse) async def redoc_ui(): return get_redoc_html( openapi_urlapp.openapi_url, titleapp.title, redoc_js_url/static/redoc.standalone.js, # 指向本地 JS )这里有个容易绕晕的点swagger_css_url不是FastAPI(...)构造函数的参数它属于get_swagger_ui_htmlReDoc 侧同理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(directorystatic)相对启动目录解析用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考