fastapi 如何让路由支持路径前缀但不影响 OpenAPI

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 里的链接就全失效。