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

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），仅供参考

企业数字化 ERP 产品动态

相关推荐

计算1！+ 2！+ 3! + 4! +···+10！（1到10的阶乘）

//初始化 int i 0; int j 1; int ret 1; int sum 0; //嵌套for循环 for (i 0; i < 10; i) //累计1到10 {for (j 1; j < i; j) //每次数的阶乘{ret ret * j;}sum sum ret; //计算每个数的阶乘相加 } printf("%d", sum);int i 1; int ret 1; int sum … · 2026/11/4 1:45:00

WinRAR

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views … · 2026/11/4 1:45:00

Windows快捷键的定义

Linux（23）：文件操作入门——从 C 文件接口到文件描述符

文件操作可以从两层接口理解：C 标准库提供 FILE * 流，Linux/POSIX 接口使用整数形式的文件描述符。两层接口最终都与进程访问文件有关，但它们提供的抽象和数据处理方式不同。本文从 fopen、fprintf、fclose 出发，再衔接 open、re… · 2026/11/4 2:35:15

XSS 攻击与防御

10.1 XSS 攻击与防御XSS 的本质可以类比为在网页里混入一段不受信任的剧本，浏览器无法区分脚本是业务本身的代码还是攻击者注入的内容，会直接解析执行，窃取数据、劫持页面、诱导跳转。10.1.1 XSS 分类：反射型、存储型、DOM 型XSS&… · 2026/11/4 2:35:15

深入理解 JUC：Callable、线程池、信号量、CountDownLatch 与 ConcurrentHashMap 全解析

深入理解 JUC：Callable、线程池、信号量、CountDownLatch 与 ConcurrentHashMap 全解析JUC（java.util.concurrent）是 JDK 提供的并发编程工具包，把多线程开发中的常见问题都给出了现成方案。本文先讲 Callable 接口与创建线程的四… · 2026/11/4 2:35:15

AgentEvals（agentevals-cli）Agent评测方法与步骤

AgentEvals（agentevals-cli）Agent评测方法与步骤框架定位与核心原理业内常说的 AgentEvals 官方全称为 agentevals-cli，是 Strands Labs 开源的框架无关、OpenTelemetry(OTel) Trace 驱动的Agent评测工具，核心设计理念是「一次… · 2026/11/4 2:35:15

【Linux网络】传输层协议TCP（2）连接管理、三次握手、四次挥手

hello~ 很高兴见到大家! 这次带来的是Linux网络中关于网络基础这部分的一些知识点,如果对你有所帮助的话,可否留下你宝贵的三连呢? 个人主页: 默|笙文章目录一、连接管理机制1.1 连接与三次握手连接管理三次握手1.2 四次挥手连接管理与理解 TIME_WAIT 状态MSL地址重用/端口… · 2026/11/4 2:35:15

Codex 做桌面理线盒：参数改一次，CAD 和 Blender 产品图一起更新

Codex 做桌面理线盒：参数改一次，CAD 和 Blender 产品图一起更新桌上充电线会从盒边滑出来，通常不是“再买一个收纳盒”能解决的问题，而是出口直径、盒内余量和桌面位置没有变成可改的尺寸。这里做一个 965822 mm 的理线盒：两侧有 10 mm 线口，盒内保留 4 mm 底厚。本文记… · 2026/11/4 2:34:15