必须先禁用 FastAPI 默认文档路由（docs_url=None, redoc_url=None），再通过 get_swagger_ui_html 注入自定义 swagger_css_url，同时配对指定 swagger_js_url 和 openapi_url，并注意 CSS 选择器优先级与浏览器缓存。
直接改 swagger_css_url 或挂载静态文件再引用，别碰默认文档路由——否则样式不生效还容易被 CDN 覆盖。
禁用默认文档路由是前提
FastAPI 的 docs_url 和 redoc_url 一开启，就自动走内置 HTML 模板，你挂的 CSS 根本没机会加载。必须先关掉：
app = FastAPI(docs_url=None, redoc_url=None)- 关掉后，
/docs和/redoc路径 404，你才能自己注册路由 - 如果只关一个（比如只关
redoc_url），另一个仍会抢资源、干扰自定义逻辑
用 get_swagger_ui_html 注入自定义 CSS 链接
这是最轻量、最可控的方式，适合换 CDN 或加一层本地样式：
- 调用
get_swagger_ui_html时传入swagger_css_url参数，值为你的 CSS 地址 - 地址可以是：
https://unpkg.com/swagger-ui-dist@5/swagger-ui.css（国内快）、/static/custom.css（需提前挂载StaticFiles） - 注意：
swagger_js_url也得一起指定，否则 JS 和 CSS 版本不匹配，UI 可能白屏或错位 - 示例中
openapi_url必须显式传，不能依赖默认值——某些部署环境下它可能不是/openapi.json
自托管 CSS 文件要配对挂载静态目录
想彻底脱离 CDN、做离线部署或深度定制，就得把 CSS 文件放到项目里：
立即学习“前端免费学习笔记（深入）”；
- 建
static/目录，放custom-swagger.css - 用
app.mount("/static", StaticFiles(directory="static"), name="static")挂载 - 在
get_swagger_ui_html中写swagger_css_url="/static/custom-swagger.css" - CSS 里选类名要小心：
.swagger-ui .topbar这种带前缀的才安全；直接写body或h1容易被 Swagger 自身样式覆盖
别忽略 swagger_ui_parameters 的内建配置项
有些样式效果根本不用写 CSS，FastAPI 已经封装好了参数接口：
-
swagger_ui_parameters={"syntaxHighlight": {"theme": "nord"}}—— 直接切语法高亮主题，比手写 CSS 稳定 -
{"deepLinking": False}—— 关掉 URL 锚点跳转，避免前端路由冲突 -
{"defaultModelsExpandDepth": -1}—— 折叠 Schema，默认展开太占屏 - 这些参数和自定义 CSS 不冲突，但优先级低于 CSS；有重叠功能时，建议优先用参数，更少维护成本
真正难的不是加一行 swagger_css_url，而是 CSS 选择器得压过 Swagger 自带的千行样式规则；改完记得清浏览器缓存，否则常看到“明明改了却没变”的假象。
