FastAPI 输入/输出 OpenAPI Schema 分离机制与 separate_input_output_schemas 参数详解【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi自 Pydantic v2 起FastAPI 生成的 OpenAPI 文档变得更加精确同一个 Pydantic 模型在请求体输入和响应体输出两种角色下可能会生成两个不同的 JSON Schema——因为带默认值的字段在两种场景下的必填语义不同。本文基于官方文档separate-openapi-schemas教程结合仓库中fastapi/applications.py、fastapi/_compat/v2.py的源码实现与测试用例完整讲清这一机制的工作原理、对自动生成的客户端/SDK 的意义以及如何用separate_input_output_schemasFalse关闭 Schema 分离以保持客户端兼容性。问题背景一个模型两种必填语义考虑下面这个带默认值的 Pydantic 模型来自 教程示例文件from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None None关键在于description: str | None None这一行它声明了默认值None。这个默认值会让该字段在输入与输出场景下产生不同的必填语义作为输入请求体时客户端可以不传description因为缺失时会自动使用默认值None——所以它是非必填字段作为输出响应体时序列化后的 JSON 中该字段一定存在没设置时就是null客户端无需判断字段是否存在可以直接假设它总在响应里——所以它应该被标记为必填字段。OpenAPI 描述字段总是存在的方式就是把它列入required列表。于是同一个Item模型在输入和输出两种用途下需要两个不同的 JSON Schema。完整示例同一模型同时用作输入和输出下面是一个最小可运行的完整示例docs_src/separate_openapi_schemas/tutorial001_py310.py全文from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None None app FastAPI() app.post(/items/) def create_item(item: Item): return item app.get(/items/) def read_items() - list[Item]: return [ Item( namePortal Gun, descriptionDevice to travel through the multi-rick-verse, ), Item(namePlumbus), ]两个接口分别演示了模型的双重角色app.post(/items/)中item: Item把Item用作输入请求体校验app.get(/items/)的返回值注解- list[Item]把Item用作输出响应序列化与文档描述。输入视角description 非必填当Item用作请求体时description由于有默认值None不是必填字段。在 Swagger UI 中查看Item-Inputdescription字段没有红色星号标记即未被标记为 required。输出视角description 必填但值可以是 null当Item用作响应时情况不同即使你的代码没有给description赋任何值如示例中的Item(namePlumbus)序列化后的 JSON 响应中仍然会出现description: null——因为该字段有默认值序列化时一定会输出。这意味着使用你 API 的客户端不需要检查该字段是否存在可以假设字段始终在响应中只是某些情况下值为NoneJSON 中的null。在 OpenAPI 中描述这一点的方式就是把该字段标记为required因为它始终会出现。因此一个模型的 JSON Schema 会根据其用途输入或输出而不同作为输入时description非必填作为输出时description必填且可能为null。OpenAPI 中的两个 SchemaItem-Input 与 Item-Output在 Swagger UI 的 Schemas 面板中见文首截图可以看到同一个Item模型生成了两个 SchemaItem-Inputdescription无红色星号非必填Item-Outputdescription带红色星号必填。这个行为正是 Pydantic v2 提供的能力它区分校验模式validation与序列化模式serialization分别生成各自精确的 JSON Schema。FastAPI 直接利用了这一能力使 API 文档更精确如果你的客户端/SDK 是由 OpenAPI 文档自动生成的生成的代码同样会更精确、更具一致性——比如输出模型中description会被生成为非可空缺省的字段而不是可选字段。源码纵深分离机制是如何实现的这一行为的开关贯穿 FastAPI 的 OpenAPI 生成调用链可以沿以下源码路径追踪应用入口fastapi/applications.py 中FastAPI.__init__定义参数separate_input_output_schemas: Annotated[bool, ...]默认True保存为实例属性其内联文档还以tags: list[str] []为例解释了输入/输出 Schema 差异。在生成 OpenAPI 时约applications.py第 1099 行该属性被传入get_openapi()separate_input_output_schemasself.separate_input_output_schemas,OpenAPI 生成fastapi/openapi/utils.py 中get_openapi()、get_openapi_path_item()等函数层层透传separate_input_output_schemas最终传给 Pydantic 兼容层的 Schema 生成函数。核心判定逻辑fastapi/_compat/v2.py 中的get_definitions()与get_schema_from_model_field()是该机制的落点。关键逻辑是override_mode: Literal[validation] | None ( None if (separate_input_output_schemas or _has_computed_fields(field)) else validation )含义是当separate_input_output_schemasTrue默认时override_mode为None字段按其原始模式请求体为validation响应为serialization各自生成独立定义从而产出Item-Input与Item-Output两份 Schema当设为False时override_mode被强制为validation即输入与输出统一使用校验模式的 Schema对应非必填语义注意_has_computed_fields(field)分支只要模型含有computed_field计算字段就总是分离输入/输出 Schema计算字段只在输出中存在不可能在输入中出现分离是唯一正确的描述方式即使你显式设置了False。测试用例佐证仓库中的 tests/test_openapi_separate_input_output_schemas.py 用快照完整验证了两种模式下的/openapi.json输出默认模式下components.schemas中同时存在Item-Inputrequired: [name]与Item-Outputrequired: [name, description, sub]请求体引用#/components/schemas/Item-Input响应引用#/components/schemas/Item-Output设置separate_input_output_schemasFalse后只有单一的Itemrequired: [name]输入与输出均引用#/components/schemas/Item该测试还验证了含computed_field的WithComputedField模型在False模式下依然保持WithComputedField-Input/WithComputedField-Output分离——与上文源码中_has_computed_fields的强制分支完全对应。此外嵌套模型同样会各自分离如测试中的SubItem-Input与SubItem-Output而模型上的model_config {json_schema_serialization_defaults_required: True}配置见该测试文件第 11、18 行则控制 Pydantic 在序列化模式下是否把带默认值的字段一律标记为 required是理解输出 Schemarequired列表细节的配套机制。关闭分离separate_input_output_schemasFalse某些场景下你可能希望输入和输出共用同一个 Schema。文档中给出的主要用例是你已经基于 OpenAPI 文档生成了一批客户端代码/SDK暂时不想重新生成、更新所有客户端——未来会做但现在不做。此时可以关闭该功能from fastapi import FastAPI from pydantic import BaseModel class Item(BaseModel): name: str description: str | None None app FastAPI(separate_input_output_schemasFalse) app.post(/items/) def create_item(item: Item): return item app.get(/items/) def read_items() - list[Item]: return [ Item( namePortal Gun, descriptionDevice to travel through the multi-rick-verse, ), Item(namePlumbus), ]注意separate_input_output_schemas参数的支持是从 FastAPI0.102.0版本开始加入的。关闭后/openapi.json中只剩一个SchemaItem输入和输出都引用它且description被标记为非必填采用校验模式的语义。实践建议与小结默认保持开启separate_input_output_schemas默认为True生成的文档对 API 消费者尤其是自动生成客户端的描述最精确——输出模型中带默认值的字段保证存在客户端可据此生成更严格的类型与反序列化逻辑。仅在兼容性需要时关闭当你已发布自动生成的 SDK 且不想引发客户端侧的模型变更Item变成Item-Input/Item-Output两个新类型时临时设为False待客户端统一升级后再恢复默认行为。注意例外含computed_field的模型无论如何都会分离输入/输出 Schema这是语义正确性的必然要求不是配置失误。验证方式运行应用后直接查看/openapi.json的components.schemas或用 Swagger UI/docs的 Schemas 面板确认-Input/-Output后缀与红色星号是否符合预期仓库中 test_openapi_schema_no_separate 的快照可视为关闭模式下 OpenAPI 输出的标准参照。参考文件文档separate-openapi-schemas.md示例代码tutorial001_py310.py、tutorial002_py310.py核心源码fastapi/applications.py、fastapi/openapi/utils.py、fastapi/_compat/v2.py测试tests/test_openapi_separate_input_output_schemas.py【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考