FastAPI 定制 OpenAPI Schema：覆盖 app.openapi() 与 get_openapi() 工具函数的完整实践

FastAPI 定制 OpenAPI Schema覆盖 app.openapi() 与 get_openapi() 工具函数的完整实践【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi在需要为 API 文档加入自定义扩展如 ReDoc 的x-logo标志、企业级元数据时FastAPI 允许在保持默认行为的基础上直接干预 OpenAPI Schema 的生成过程。本文基于官方文档 Extending OpenAPI结合 fastapi/applications.py 与 fastapi/openapi/utils.py 源码讲清楚默认 Schema 的生成链路、get_openapi()的完整参数、以及如何用“生成—修改—缓存—替换方法”四步完成对.openapi()的安全覆盖。一、默认流程OpenAPI Schema 从哪里来一个FastAPI应用实例带有一个.openapi()方法它负责返回应用的 OpenAPI Schema。在应用对象创建阶段setup()会注册一个/openapi.json即openapi_url配置值路径操作其处理函数直接返回self.openapi()结果的 JSON 响应。这一点可以在 setup() 实现 中确认def setup(self) - None: if self.openapi_url: async def openapi(req: Request) - JSONResponse: root_path req.scope.get(root_path, ).rstrip(/) schema self.openapi() # 若启用了 root_path_in_servers会把 root_path 注入 servers ... return JSONResponse(schema) self.add_route(self.openapi_url, openapi, include_in_schemaFalse)默认情况下.openapi()的逻辑是检查属性.openapi_schema是否已有内容有则直接返回没有则调用工具函数fastapi.openapi.utils.get_openapi生成。当前源码实现fastapi/applications.py#L1070-L1103还额外引入了路由版本检查——当路由树发生变化routes_version改变时缓存会失效并重新生成def openapi(self) - dict[str, Any]: routes_version self.router._get_routes_version() if not self.openapi_schema or self._openapi_routes_version ! routes_version: self.openapi_schema get_openapi( titleself.title, versionself.version, openapi_versionself.openapi_version, summaryself.summary, descriptionself.description, ... routesself.routes, webhooksself.webhooks.routes, ... ) self._openapi_routes_version routes_version return self.openapi_schema这说明框架本身已经内置了“缓存 失效”机制官方文档中教我们手动实现缓存正是复现并延伸这一默认行为。get_openapi() 的参数说明文档明确列出的核心参数如下参数含义titleOpenAPI 标题显示在文档页面version你的 API 版本号例如2.5.0openapi_version使用的 OpenAPI 规范版本默认取最新值3.1.0summaryAPI 的简短摘要descriptionAPI 描述支持 Markdown会显示在文档页面routes应用的路由取自app.routes。FastAPI 用它收集已注册的 path operations包括各 router 纳入的路由从源码签名看get_openapi 定义get_openapi()还支持一批文档未逐一展开的可选参数在需要更深定制时可以一并利用def get_openapi( *, title: str, version: str, openapi_version: str 3.1.0, summary: str | None None, description: str | None None, routes: Sequence[BaseRoute | routing.RouteContext], webhooks: Sequence[BaseRoute | routing.RouteContext] | None None, tags: list[dict[str, Any]] | None None, servers: list[dict[str, str | Any]] | None None, terms_of_service: str | None None, contact: dict[str, str | Any] | None None, license_info: dict[str, str | Any] | None None, separate_input_output_schemas: bool True, external_docs: dict[str, Any] | None None, ) - dict[str, Any]:两个值得注意的细节summary的版本要求summary字段由 OpenAPI 3.1.0 规范引入FastAPI 自 0.99.0 起支持源码中if summary: info[summary] summaryutils.py#L602-L604。app.routes是低层路由树它可能包含 FastAPI 为 included routers 使用的内部路由候选而不只是最终的APIRoute对象。从源码结构看get_openapi()通过routing.iter_route_contexts(routes)递归遍历该路由树收集真正生效的 path operations因此直接把app.routes传给它没有问题。二、覆盖默认行为生成—修改—缓存—替换核心思路用同一个get_openapi()工具函数生成基础 Schema然后按需修改其中的任意部分。下面以 ReDoc 的 OpenAPI 扩展为例给info对象添加自定义x-logo字段。第 1 步按正常方式编写 FastAPI 应用应用代码本身不需要任何特殊处理对应 docs_src/extending_openapi/tutorial001_py310.pyfrom fastapi import FastAPI from fastapi.openapi.utils import get_openapi app FastAPI() app.get(/items/) async def read_items(): return [{name: Foo}]第 2 步用工具函数生成 OpenAPI Schema在custom_openapi()函数内调用get_openapi()传入你需要的title、version、summary、description与routesapp.routesdef custom_openapi(): if app.openapi_schema: return app.openapi_schema openapi_schema get_openapi( titleCustom title, version2.5.0, summaryThis is a very custom OpenAPI schema, descriptionHeres a longer description of the custom **OpenAPI** schema, routesapp.routes, )第 3 步修改 Schema此时 Schema 就是一个普通的 Python dict可以直接增改任意字段。本例添加 ReDoc 的x-logo扩展openapi_schema[info][x-logo] { url: https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png }第 4 步把 Schema 写入.openapi_schema作为缓存用.openapi_schema属性存储生成结果这样应用不必在每次有人打开 API 文档时都重新生成 Schema——它只生成一次后续请求直接返回缓存app.openapi_schema openapi_schema return app.openapi_schema第 5 步替换.openapi()方法最后一行把应用的方法整体替换为你的自定义函数app.openapi custom_openapi完整示例即为 tutorial001_py310.py 全文。启动后访问http://127.0.0.1:8000/redoc可以看到 ReDoc 页面左上角使用了你配置的自定义 Logo示例中使用的是 FastAPI 的 Logo访问/docs则能看到定制的title、summary与 Markdown 描述的description。三、源码级验证缓存、路由版本与测试用例官方测试如何验证定制效果仓库自带针对该示例的测试 tests/test_tutorial/test_extending_openapi/test_tutorial001.py它做了两件事请求/openapi.json用快照断言确认返回的info中确实包含定制的title、summary、description以及x-logo扩展再次请求/openapi.json断言两次返回完全一致——以此验证自定义缓存路径直接命中app.openapi_schema早返回工作正常。def test_openapi_schema(): response client.get(/openapi.json) assert response.json() snapshot({ openapi: 3.1.0, info: { title: Custom title, summary: This is a very custom OpenAPI schema, description: Heres a longer description of the custom **OpenAPI** schema, version: 2.5.0, x-logo: {url: https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png}, }, paths: {/items/: {get: {...}}}, })默认流程中缓存的细节对比默认实现可以看到手动缓存if app.openapi_schema: return app.openapi_schema与框架内置缓存是同一设计意图但框架版本更严谨它在路由树版本变化时会丢弃旧 Schema 重新生成applications.py#L1084-L1095。如果你采用手动覆盖方案且运行期间通过app.include_router()等方式动态注册新路由需要自行评估是否也要处理失效逻辑。/openapi.json 响应的附加行为从 setup() 源码 还可以看到当请求携带root_path如部署在反向代理子路径下且启用了root_path_in_servers时框架会把root_path注入servers字段后再返回。这一行为发生在.openapi()之外因此你手动定制 Schema 时不受影响两者互不干扰。四、小结适用场景与注意事项适用场景向info注入文档工具专属扩展x-logo、x-前缀自定义字段、重写servers/tags/externalDocs等默认不暴露给FastAPI()构造参数的字段或对整份 Schema 做程序化改写。实现要点始终复用get_openapi()而非从零拼装 dict保证路径、参数、组件等结构与官方生成完全一致修改操作只作用于其返回的 dict 副本语义上最后写回app.openapi_schema并执行app.openapi custom_openapi。限制summary仅在 OpenAPI 3.1.0 下进入输出直接替换方法后框架内置的“路由版本变化自动失效”缓存策略不再作用于你的自定义实现长期动态变更路由的场景需谨慎。掌握以上链路后你可以对/openapi.json的输出内容做到任意程度、可测试、可复现的精确控制。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考