FastAPI默认内置Swagger UI和ReDoc文档界面，分别位于/docs和/redoc路径，依赖动态生成的/openapi.json；禁用路径不等于隐藏API契约，需谨慎配置中间件与环境判断。
FastAPI 默认就带 Swagger UI，不用额外装包
只要用 FastAPI() 实例启动服务，默认在 /docs 路径就能打开 Swagger UI。它不是“生成静态 HTML”，而是运行时动态渲染的交互式文档——所以没配好路由或没跑服务，就打不开页面。
- 确保
app = FastAPI()没加docs_url=None或redoc_url=None这类禁用参数 - 开发环境默认开启；生产部署时如果用了反向代理（比如 Nginx），要确认
/docs和/redoc路径没被拦截或重写 - Swagger UI 依赖
/openapi.json接口返回标准 OpenAPI v3 JSON，这个接口不能被中间件过滤或鉴权拦住
ReDoc 页面在 /redoc，但不支持所有 OpenAPI 扩展字段
ReDoc 是另一个内置文档界面，路径是 /redoc，视觉更简洁、适合嵌入文档站。但它对某些 FastAPI 自动生成的字段兼容性较弱，比如带 examples 或自定义 response_model_exclude_unset=True 的接口，可能显示为空响应体或丢失示例值。
- 若发现 ReDoc 里响应结构缺失，先检查模型字段是否加了
Field(default=...)或Optional声明不明确 - ReDoc 不识别
deprecated=True的接口标记，Swagger UI 可以——需要标注弃用时优先看 Swagger - 想换掉默认路径？可以初始化时改：
FastAPI(redoc_url="/api/docs")，但别设成和/docs冲突
OpenAPI JSON 是文档源头，改它等于改所有界面
/openapi.json 是 Swagger UI 和 ReDoc 共用的数据源，FastAPI 自动生成它。如果你手动改了 app.openapi() 方法，或者用中间件篡改了该路径响应，两个界面都会同步出问题。
- 常见错误：在中间件里对所有 JSON 响应统一加
{"data": ...}包裹，结果把/openapi.json也包了，导致 UI 加载失败并报错Failed to load spec - 想定制 OpenAPI 内容？用
app.openapi_schema缓存 + 条件重建，而不是覆盖app.openapi方法 - 加全局 tags、servers、externalDocs？直接传给
FastAPI()初始化参数，比后期 patch 更稳
关闭文档只关路径，不删 OpenAPI 数据
设 docs_url=None 只是让 /docs 返回 404，并不会影响 /openapi.json 输出。很多团队误以为“关了 docs 就安全了”，其实攻击者仍可拿到完整接口定义。
立即学习“Python免费学习笔记（深入）”；
- 真要隐藏接口契约？得同时禁用
openapi_url=None，但这会让所有文档界面彻底失效（包括自己调试） - 更实际的做法：用中间件对
/openapi.json做环境判断，比如只在DEBUG=True时返回内容 - 注意：
redoc_url=None和docs_url=None互不影响，可以只留一个
真正容易被忽略的是 OpenAPI JSON 的生成时机——它首次访问 /openapi.json 才构建，期间若模型引用了还没 import 的模块，会直接 500。所以文档路径看似“自动”，背后仍卡在代码加载顺序上。
