fastapi中openapi文档未更新因内存缓存，需设app.openapi_schema=none并覆盖/openapi.json路由；pydantic v2字段丢失需显式指定example或类型；多版本应分路径隔离；ci校验失败多因$ref路径上下文不一致。
OpenAPI YAML 文件改了但接口文档没更新
本地改完 openapi.yaml，用 swagger-ui 或 redoc 本地预览时文档还是旧的，不是缓存问题，是服务压根没重新加载。常见于用 fastapi 自带的 docs 路由或用 swagger-ui-dist 静态托管的场景。
- FastAPI 默认把 OpenAPI schema 缓存在内存里，
app.openapi()返回的是缓存结果，不是实时生成的 —— 修改 YAML 不会自动触发重载 - 如果用
fastapi.staticfiles.StaticFiles托管openapi.yaml，得确保路径正确且 MIME 类型为application/vnd.oai.openapi+json（YAML 需转 JSON 或用支持 YAML 的 UI） - 推荐做法：别手动维护独立 YAML 文件，让框架生成；若必须手写 YAML，就用
app.openapi_schema = None强制下次请求重建，再加个@app.get("/openapi.json")覆盖路由返回最新内容
用 Pydantic v2 模型生成 OpenAPI 时字段丢失
升级到 FastAPI 0.104+ 或单独用 Pydantic v2 后，Field(default_factory=list) 或嵌套 Optional[dict] 在 OpenAPI 输出里变成 type: string 或直接消失，不是模型写错了，是 schema 生成逻辑变了。
- Pydantic v2 默认不为
default_factory推导类型，需显式加example或default，比如items: List[str] = Field(default_factory=list, example=[]) -
Optional[Dict]会被当成Any处理，OpenAPI 不认，换成dict | None（Python 3.10+）或Optional[Dict[str, Any]]并配example={} - 字段上用了
alias但没设validation_alias，会导致 OpenAPI 里字段名对不上，尤其在请求体校验时静默失败
多个 API 版本共存时 OpenAPI 标题/版本号混乱
项目同时跑 /v1/ 和 /v2/ 路由，但 openapi.json 里 info.version 只有一个值，Swagger UI 切换版本后 schema 还是混的 —— OpenAPI 本身不原生支持多版本聚合，得靠组织方式补位。
- 别指望单个
openapi.json描述所有版本，每个版本应有独立文档入口，比如/v1/openapi.json和/v2/openapi.json - FastAPI 的
title和version是全局配置，启动多个FastAPI()实例时，每个实例要传不同title和version，不能复用同一个 app 对象 - 如果用 Nginx 或网关做版本路由，OpenAPI 文档路径也得对应代理，否则
server.url写成http://localhost:8000/v1却被代理到/，请求会 404
CI 环境里 OpenAPI 校验失败但本地正常
openapi-spec-validator 或 spectral 在 CI 报 schema is not valid，错误指向某个 $ref 找不到，而本地 openapi.yaml 能被 VS Code 插件正常解析 —— 根本原因是相对路径解析上下文不同。
立即学习“Python免费学习笔记（深入）”；
- CI 中运行校验工具时工作目录往往不是 YAML 所在目录，
$ref: "./components/schemas/User.yaml"会按 CI 当前路径找，不是按 YAML 文件位置找 - 解决方法：用
openapi-spec-validator --base-url file://$(pwd)/path/to/显式指定基准路径，或统一用绝对$ref（如file:///abs/path/components/schemas/User.yaml） - YAML 内联引用（
$ref: "#/components/schemas/User"）没问题，但跨文件引用必须保证所有被引文件可访问，且工具支持递归解析（spectral默认不展开外部 $ref，得加--resolve-external）
OpenAPI 维护最麻烦的从来不是语法，而是“谁在什么时候、以什么上下文读这份 YAML”。路径、缓存、版本隔离、工具链差异——每个点都可能让文档和实际行为脱节，而且错得悄无声息。
