fastapi 中用 openapi_prefix="/api/v1" 配合 include_router(..., prefix="/api/v1") 可实现路由匹配带前缀而 openapi 文档路径干净：前者仅修改 openapi json 中 paths 前缀，后者控制实际请求路由；二者缺一不可，且 openapi_prefix 不能以 / 结尾。
FastAPI 的 include_router 前缀如何不污染 OpenAPI 标题和路径
直接用 include_router(app, prefix="/api/v1") 会导致 OpenAPI 文档里所有路径带前缀，且 title 和 description 也会被覆盖——这不是你想要的“路由有前缀，但文档干净”的效果。
根本原因是 FastAPI 默认把 prefix 当作路径一部分透传给 OpenAPI Generator。解决思路是：让路由逻辑走前缀，但 OpenAPI 元数据保持原始定义。
- 用
include_router(..., prefix="/api/v1", include_in_schema=False)关掉该 router 的自动注册，再手动添加到app.openapi()生成逻辑中（太重，不推荐） - 更轻量的做法：保留
prefix，但为每个APIRoute显式设置include_in_schema=True并重写path字段（见下一条） - 最稳妥的方式：在挂载 router 时用
tags+ 独立openapi_prefix配合中间件做路径剥离（实际生效的是这个）
用 openapi_prefix 分离运行时路径与 OpenAPI 路径
openapi_prefix 是 FastAPI 提供的专用字段，它只影响 OpenAPI JSON 中的 paths 键路径前缀，不影响实际请求匹配——这正是你需要的分离能力。
假设你部署在 Nginx 后，真实访问地址是 https://example.com/api/v1/items，但希望 OpenAPI 文档显示为 /items：
app = FastAPI(
openapi_prefix="/api/v1",
)
注意：openapi_prefix 不会改变路由匹配行为，它只改 OpenAPI 输出里的 paths 值。所以你仍需用 include_router(..., prefix="/api/v1") 来保证请求能进到对应 router。
- 二者必须配合使用：
prefix控制匹配，openapi_prefix控制文档路径 - 如果只设
openapi_prefix不设prefix，请求 404；只设prefix不设openapi_prefix，文档路径冗长 -
openapi_prefix不能以/结尾，否则 OpenAPI 里路径会多出双斜杠（如//items）
Router 挂载时避免 tags 冲突导致 OpenAPI 分组错乱
多个 router 如果都用相同 tags=["items"]，即使路径不同，OpenAPI 也会把它们合并到同一分组下，掩盖前缀差异。这不是 bug，是 OpenAPI spec 的设计逻辑。
正确做法是：按前缀语义区分 tags，比如：
router_v1 = APIRouter(tags=["v1-items"]) router_v2 = APIRouter(tags=["v2-items"]) app.include_router(router_v1, prefix="/api/v1") app.include_router(router_v2, prefix="/api/v2")
- 标签名不需要和 prefix 完全一致，但要有可区分性，否则 UI 展开后无法识别哪组属于哪个版本
- 如果 router 内部用了
response_model，确保模型名不重复（FastAPI 用类名生成 schema key），否则 OpenAPI 里会覆盖 - 用
generate_unique_id_function可进一步避免 operationId 冲突，尤其当两个 router 有同名@router.get("/status")时
调试 OpenAPI 路径是否生效的三个检查点
改完配置后，别急着信文档，用这三个地方交叉验证：
- 访问
/docs，打开浏览器开发者工具 → Network → 点 “GET /openapi.json”，看返回 JSON 中paths下的键是否已剔除/api/v1 - 在 Python REPL 中执行
app.routes，确认每个APIRoute的path属性仍含前缀（说明匹配逻辑没坏） -
curl
http://localhost:8000/api/v1/items必须返回 200，而/items必须 404（证明 prefix 生效且没泄漏）
最容易忽略的是：本地开发时用 uvicorn.run(app)，但部署到反向代理后忘了同步配置 openapi_prefix —— 它必须和反向代理暴露的路径严格一致，差一个字符，OpenAPI 里的链接就全失效。
