FastAPI API 文档界面定制指南3步自托管 CSS 与 2 个主题配置场景【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapiFastAPI 生成的/docs与/redoc页面默认从外部 CDN 拉取 Swagger UI 和 ReDoc 的 JS、CSS样式不可动。如果你的服务部署在内网或希望文档页贴合公司品牌色不需要改框架内部——替换资源地址、注入自己的 CSS 即可所需的钩子 FastAPI 都留好了。最终效果完成自托管后打开/docs依旧是那个 Swagger UI 界面但swagger-ui-bundle.js、swagger-ui.css、redoc.standalone.js全部来自你自己的/static路径请求体里的 JSON 示例换成 obsidian 高亮主题顶栏和 Try it out 按钮由你的 CSS 重新上色。浏览器 Network 面板里不再出现任何外部 CDN 的请求。最短路径最小配置只做三件事关掉内置文档、挂载静态目录、注册自己的/docs路由。核心函数在 fastapi/openapi/docs.py 里完整写法可参考 docs_src/custom_docs_ui/tutorial002_py310.py。第一行禁用内置文档路由把/docs和/redoc收归自己管理from fastapi import FastAPI app FastAPI(docs_urlNone, redoc_urlNone) # 关掉内置 /docs、/redoc把static/目录挂到/staticURL 上让浏览器能访问 CSS 文件from fastapi.staticfiles import StaticFiles app.mount(/static, StaticFiles(directorystatic), namestatic)注册自定义/docs把 CSS 指向本地文件from fastapi.openapi.docs import get_swagger_ui_html app.get(/docs, include_in_schemaFalse) async def custom_swagger_ui_html(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titleapp.title - Swagger UI, swagger_css_url/static/swagger-ui.css, # 指向本地 CSS )品牌样式写在自己的 CSS 里直接追加热好的swagger-ui.css末尾即可覆盖同名规则/* 覆盖官方 swagger-ui.css 中的同名规则 */ .swagger-ui .topbar { background-color: #2c3e50; } .swagger-ui .info h2 { color: #3498db; }有一个硬约束get_swagger_ui_html生成的 HTML 里只有一个linkCSS 位所以官方 CSS 自定义 CSS必须合并成一份文件交付另开一个styles.css是没人会引用的。场景化方案场景一内网/离线环境全量自托管 公司网络访问不了任何公网地址时把 Swagger UI 和 ReDoc 三个文件全部下载到static/走本地路径from fastapi.openapi.docs import ( get_redoc_html, get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html, ) app FastAPI(docs_urlNone, redoc_urlNone) app.mount(/static, StaticFiles(directorystatic), namestatic) app.get(/docs, include_in_schemaFalse) async def custom_swagger_ui_html(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titleapp.title - Swagger UI, oauth2_redirect_urlapp.swagger_ui_oauth2_redirect_url, swagger_js_url/static/swagger-ui-bundle.js, swagger_css_url/static/swagger-ui.css, )ReDoc 侧只需换 JS 地址它的样式打包在 standalone 文件里没有独立的 CSS 参数app.get(/redoc, include_in_schemaFalse) async def redoc_html(): return get_redoc_html( openapi_urlapp.openapi_url, titleapp.title - ReDoc, redoc_js_url/static/redoc.standalone.js, )注意如果 API 用了 OAuth2 的 Authorize 按钮必须同时注册get_swagger_ui_oauth2_redirect_html()对应的回调路由否则授权流程会断在最后一步。场景二品牌 VI 统一切换 Swagger UI 语法高亮主题 大多数团队不想大改界面只希望高亮配色和代码风格统一。swagger_ui_parameters会原样透传给 Swagger UI构造时传一个字典就行from fastapi import FastAPI # theme 取 highlight.js 内置主题名如 arta、monokai、nord、obsidian app FastAPI( swagger_ui_parameters{syntaxHighlight: {theme: obsidian}} )顶栏、按钮等结构性样式则交给上面的自定义 CSS 接管。两个入口一个管高亮配色一个管整体视觉互不干扰。场景三生产环境钉住静态资源版本默认配置里 CDN 地址用的是swagger-ui-dist5这种浮动版本上游发新版后你的文档页样式会悄悄变化。自托管正好解决这个问题——版本由你下载哪个 release 决定app FastAPI(docs_urlNone) app.get(/docs, include_in_schemaFalse) async def custom_swagger_ui_html(): return get_swagger_ui_html( openapi_urlapp.openapi_url, titleapp.title - Swagger UI, swagger_js_url/static/swagger-ui-bundle.js, swagger_css_url/static/swagger-ui.css, )注意swagger_js_url和swagger_css_url必须来自同一个 release。混用不同版本会出现按钮错位、响应区塌陷这类样式漂移且控制台不会报任何错。对比与验证项目默认状态自托管 定制后CSS 来源jsdelivr CDN本地/static/swagger-ui.css请求体 JSON 高亮highlight.js 默认主题obsidian 橙红色主题顶栏 / 按钮配色官方默认蓝自己 CSS 定义的品牌色默认主题下示例值里的字符串是绿色换成syntaxHighlight.theme obsidian后同一位置的字符串变成橙红色验证方法打开浏览器 Network 面板刷新/docs确认swagger-ui.css、swagger-ui-bundle.js的请求来源是127.0.0.1:8000/static/...而非 CDN 域名。更多细节见 Custom Docs UI Static Assets 官方文档 和 Configure Swagger UI 官方文档。高频坑排查现象TypeError: __init__() got an unexpected keyword argument swagger_css_url→ 原因swagger_css_url、swagger_js_url是get_swagger_ui_html()的参数不是FastAPI()构造函数的参数直接传给FastAPI()必然报错 → 解法按禁用内置路由 自定义/docs路由的流程走资源地址在get_swagger_ui_html()里指定。现象启动即抛RuntimeError: Directory static does not exist→ 原因StaticFiles默认在启动时校验目录存在check_dirTrue → 解法先把static/目录建好、把三个文件下载进去再启动服务check_dirFalse虽然能绕过但页面加载时照样 404不要这么干。现象改了配置Network 里仍出现 jsdelivr 的swagger-ui.css请求→ 原因创建FastAPI()时没有传docs_urlNone, redoc_urlNone内置/docs路由在构造时已注册且先于自定义路由匹配你的自定义路由根本没被命中 → 解法构造时显式置None禁用内置文档再用 Network 面板复查资源来源。自托管解决连得上swagger_ui_parameters解决看得顺自己的 CSS 解决像自己家。如果现在就要动手最划算的顺序是先切一个syntaxHighlight主题让高亮跟上团队风格再把 CDN 资源逐步搬进/static——Network 面板里 jsdelivr 请求归零的那一刻改造就算完成。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考