FastAPI 附加响应（Additional Responses）实战指南：用 `responses` 参数扩展 OpenAPI 与 API 文档

FastAPI 附加响应（Additional Responses）实战指南：用responses参数扩展 OpenAPI 与 API 文档

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

本文基于 FastAPI 官方文档进阶篇 "Additional Responses in OpenAPI"（对应仓库中的 docs/pt/docs/advanced/additional-responses.md 及同主题英文版 docs/en/docs/advanced/additional-responses.md）整理展开，并结合当前仓库源码对底层实现进行验证与补充。

response_model只能描述一条"主响应"（默认 200），而真实 API 往往还需要声明 404、403、302 等异常响应、同一端点返回 JSON 与图片等不同媒体类型，以及自定义description、example、headers、links。本文讲解 FastAPI 通过路径操作装饰器的responses参数为 OpenAPI 模式与自动 API 文档（Swagger UI / ReDoc）补充这类附加响应的完整写法与底层原理。读完你将掌握：带 Pydanticmodel的附加响应、为主响应追加额外媒体类型、用**字典解包复用预定义响应，并理解这些配置最终如何被转换进 OpenAPI 的responses与components.schemas。

⚠️ 这是一个相当高级的话题。如果你刚开始学习 FastAPI，很可能暂时用不到；可以先聚焦 response_model 文档（中文版见 docs/zh/docs/tutorial/response-model.md），掌握后再回来阅读本文。

一、附加响应的核心思路与前置约束

你可以用附加的状态码、媒体类型、描述等声明附加响应。这些附加响应会被写入 OpenAPI 模式，因此也会出现在 API 文档中。例如一个GET /items/{item_id}除了正常返回 200 的Item，还可能返回 404 的Message，二者都需要在文档里被清楚描述。

需要特别强调的前置约束是：对于这些附加响应，你必须确保自己直接返回一个Response（如JSONResponse、FileResponse），并在其中携带对应的状态码与内容。也就是说，responses参数只负责"告诉 OpenAPI/文档这个端点可能返回什么"；而真正把对应响应发回客户端，需要你在路由函数里用return JSONResponse(status_code=404, content=...)之类的方式显式完成。FastAPI 不会替附加响应做自动序列化与状态码设置。

这一约束对应一个实现细节：附加响应并不会经过response_model那套"自动过滤与校验并写入 response body"的流程，而是由函数直接返回的 Response 原样透传。

responses参数的数据结构

responses是传给路径操作装饰器（@app.get、@app.post等）的一个dict：

• 键：每个响应的状态码，如200、404、302；键也可写作"default"等 OpenAPI 允许的形式；
• 值：另一个dict，存放该响应的信息（description、content、headers、links等，并可含 FastAPI 专有的model键）。

responses={ 404: {"description": "Item not found"}, 200: {"content": {"image/png": {}}}, }

在生成的 OpenAPI JSON 中，这些数字键会自动序列化为字符串键（OpenAPI 规范要求响应键必须是字符串形式的状态码）。

二、带model的附加响应（Additional Response withmodel）

responses中每个响应的dict都可以有一个model键，里面放一个 Pydantic 模型，用法与response_model类似。FastAPI会取出该模型，为其生成 JSON Schema，并放到 OpenAPI 中正确的位置。

以官方示例 docs_src/additional_responses/tutorial001_py310.py 为例——声明一个带状态码404、模型为Message的附加响应：

from fastapi import FastAPI from fastapi.responses import JSONResponse from pydantic import BaseModel class Item(BaseModel): id: str value: str class Message(BaseModel): message: str app = FastAPI() @app.get("/items/{item_id}", response_model=Item, responses={404: {"model": Message}}) async def read_item(item_id: str): if item_id == "foo": return {"id": "foo", "value": "there goes my hero"} return JSONResponse(status_code=404, content={"message": "Item not found"})

几点关键说明：

1. 正常路径item_id == "foo"时返回普通dict，FastAPI 依据response_model=Item完成序列化；
2. 未找到时直接返回JSONResponse(status_code=404, ...)，这是前面提到前置约束的直接体现；
3. {404: {"model": Message}}让 404 响应在 OpenAPI 与文档中获得与Message对应的 Schema。

model键不是 OpenAPI 的一部分

model这个键不属于 OpenAPI 规范，它是 FastAPI 提供的便捷写法。FastAPI 会：

1. 从responses中取出 Pydantic 模型并生成 JSON Schema；
2. 把它放到正确的位置。

"正确的位置"是嵌套的 JSON 结构，逐层如下：

• 键content，其值为一个 JSON 对象（dict），其中：
  • 含一个以媒体类型命名的键，如application/json，其值为另一个 JSON 对象，其中：
    • 含键schema，其值就是模型的 JSON Schema——这里才是正确的位置。
      • 在此处，FastAPI 放的是指向全局 JSON Schema 的引用（$ref），而不是内联整个 Schema。这些全局 Schema 位于 OpenAPI 的components部分，集中存放的好处是：其他应用与客户端可以直接引用这些 JSON Schema，从而获得更好的代码生成工具支持等。

底层实现验证

这段"取model→ 生成序列化字段 → 放进 OpenAPI"的逻辑，可以从源码得到印证：

• 在 fastapi/routing.py 中，构建路由时会遍历route.responses：对每个含model的附加响应，断言该状态码允许携带响应体（is_body_allowed_for_status_code），然后以mode="serialization"创建模型字段并存入route.response_fields，供后续 OpenAPI 生成阶段使用：

response_fields = {} for additional_status_code, response in route.responses.items(): assert isinstance(response, dict), "An additional response must be a dict" model = response.get("model") if model: assert is_body_allowed_for_status_code(additional_status_code), ( f"Status code {additional_status_code} must not have a response body" ) response_name = f"Response_{additional_status_code}_{route.unique_id}" response_field = create_model_field( name=response_name, type_=model, mode="serialization" ) response_fields[additional_status_code] = response_field

（assert is_body_allowed_for_status_code(...)意味着：像204 No Content、304 Not Modified这类规范不允许带响应体的状态码，不能配合model使用，否则会在启动时抛出AssertionError。）

• 在 fastapi/openapi/utils.py 中，生成 OpenAPI 时会对route.responses逐条处理：copy.deepcopy出配置、pop("model", None)移除 FastAPI 私有键、从route.response_fields中取对应字段的 JSON Schema 并写入content[media_type]["schema"]，最后用deep_dict_update合并进 operation 的responses。注意这里取媒体类型的兜底写法media_type = route_response_media_type or "application/json"（见 fastapi/openapi/utils.py），它正是下一节"媒体类型推断规则"的代码来源。

生成的 OpenAPI

对于上面这条GET /items/{item_id}，其路径操作生成的responses如下（结构即为最终写入/openapi.json的内容）：

{ "responses": { "404": { "description": "Additional Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }

可以看到三个响应都通过$ref指向components.schemas，并未内联。同时注意：422 是 FastAPI 自动追加的——只要路径操作存在可校验的参数（本路由的item_id路径参数）或请求体，FastAPI 就会自动加入422 Validation Error响应，除非你已在响应中显式声明了422、4XX或default（对应逻辑见 fastapi/openapi/utils.py）。

关于description的补充（基于当前仓库行为的准确性提示）：上述 404 的description在原文档示例中写作"Additional Response"。需要说明的是，从当前源码看（fastapi/openapi/utils.py），FastAPI 会在未显式提供 description 时按description 或 status_text 或 "Additional Response"的顺序兜底：其中status_text来自http.client.responses（例如 404 会得到"Not Found"）。这一点在当前仓库测试 tests/test_tutorial/test_additional_responses/test_tutorial001.py 的快照中得到验证——期望值里 404 的描述正是"Not Found"。文档中的"Additional Response"体现的是未匹配到状态短语时的最终兜底文本，两种写法在不同版本/场景下都属正常，读者应以自己uvicorn启动应用后访问/openapi.json的实际输出为准。

各 Schema 则被集中定义在 OpenAPI 的components部分，被上面的$ref引用：

{ "components": { "schemas": { "Message": { "title": "Message", "required": [ "message" ], "type": "object", "properties": { "message": { "title": "Message", "type": "string" } } }, "Item": { "title": "Item", "required": [ "id", "value" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string" }, "value": { "title": "Value", "type": "string" } } }, "ValidationError": { "title": "ValidationError", "required": [ "loc", "msg", "type" ], "type": "object", "properties": { "loc": { "title": "Location", "type": "array", "items": { "type": "string" } }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } } }, "HTTPValidationError": { "title": "HTTPValidationError", "type": "object", "properties": { "detail": { "title": "Detail", "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } } } } }

说明：ValidationError/HTTPValidationError的实际输出会随 Pydantic 版本略有差异（例如当前仓库测试快照中的loc为string | integer的anyOf，并附带input、ctx等字段），上面结构用于示意整体形态。精确内容可在本仓库运行测试或请求应用/openapi.json查看。

三、为主响应附加额外的媒体类型

同一个responses参数还可以用来为主响应追加不同的媒体类型。例如声明该路径操作既可以返回 JSON 对象（媒体类型application/json），也可以返回 PNG 图片（新增媒体类型image/png）。官方示例见 docs_src/additional_responses/tutorial002_py310.py：

from fastapi import FastAPI from fastapi.responses import FileResponse from pydantic import BaseModel class Item(BaseModel): id: str value: str app = FastAPI() @app.get( "/items/{item_id}", response_model=Item, responses={ 200: { "content": {"image/png": {}}, "description": "Return the JSON item or an image.", } }, ) async def read_item(item_id: str, img: bool | None = None): if img: return FileResponse("image.png", media_type="image/png") else: return {"id": "foo", "value": "there goes my hero"}

注意这里为状态码200的content显式给出了{"image/png": {}}（空的contentdict 通常意味着"不在此声明 Schema"）。运行后访问/openapi.json，200 响应的content下会同时出现基于response_model=Item生成的application/json与手写的image/png两个分支。

同样地，返回图片时必须直接使用FileResponse（示例中用查询参数img控制返回图片还是 JSON）。因为image/png并非response_model序列化能处理的对象——文件需要FileResponse来流式发送。该文件本身并不会被 FastAPI 自动生成 Schema（OpenAPI 中图片响应通常只有媒体类型、没有内容 Schema）。

FastAPI 的媒体类型推断规则

关于附加响应的媒体类型，FastAPI 遵循以下默认规则：

• 除非你在responses里显式指定了不同的媒体类型，否则 FastAPI 假定该附加响应与主响应类（默认JSONResponse，即媒体类型application/json）保持一致；
• 如果你指定了媒体类型为None的自定义响应类，那么对于任何带有model的附加响应，FastAPI 会退而使用application/json（相关实现即上文提到的media_type = route_response_media_type or "application/json"，见 fastapi/openapi/utils.py，其中route_response_media_type从主响应类推断而来）。

也就是说：只要附加响应携带了model，就必须有一个可用的媒体类型来安放它的 JSON Schema——要么显式给出，要么沿主响应类，要么兜底为application/json。

四、组合多来源的响应信息（Combining information）

responses不是孤立的：你可以把response_model、status_code与responses三处信息组合使用，FastAPI 会保留responses中的附加信息，并与response_model生成的 JSON Schema 合并。

具体场景：声明一个response_model（默认使用状态码200，需要的话也可自定义状态码），同时在responses中为这条响应补充直接写入 OpenAPI 的额外信息。例如官方示例 docs_src/additional_responses/tutorial003_py310.py：

from fastapi import FastAPI from fastapi.responses import JSONResponse from pydantic import BaseModel class Item(BaseModel): id: str value: str class Message(BaseModel): message: str app = FastAPI() @app.get( "/items/{item_id}", response_model=Item, responses={ 404: {"model": Message, "description": "The item was not found"}, 200: { "description": "Item requested by ID", "content": { "application/json": { "example": {"id": "bar", "value": "The bar tenders"} } }, }, }, ) async def read_item(item_id: str): if item_id == "foo": return {"id": "foo", "value": "there goes my hero"} else: return JSONResponse(status_code=404, content={"message": "Item not found"})

这段代码实现了三类组合：

1. 404 响应：既用了 Pydantic 模型Message（自动生成 Schema），又给了自定义description（"The item was not found"）；
2. 200 响应：复用response_model=Item生成的 Schema，同时补上一个自定义example（{"id": "bar", "value": "The bar tenders"}）——注意这里没有写schema，FastAPI 会把response_model的ItemSchema 合并进来，形成"Schema + example"的完整描述；
3. 三处配置最终被合并进同一个responses结构。

这一点在当前仓库的测试 tests/test_tutorial/test_additional_responses/test_tutorial003.py 中有完整断言：200 分支的content["application/json"]同时含schema: {"$ref": "#/components/schemas/Item"}与手写的example，404 分支的 description 保持自定义值。合并的底层机制是 fastapi/openapi/utils.py 的deep_dict_update(openapi_response, process_response)——它会递归合并字典，而不是整层覆盖；同时 fastapi/openapi/utils.py 表明，description 的优先级是"显式 description > 已有 description > HTTP 状态短语 > 兜底文本"，因此在 200 分支中自定义 description 会替换掉默认的"Successful Response"。

合并后的结果会完整写入 OpenAPI 并展示在自动生成的 API 文档中。效果如下图所示（文档在响应区同时列出 200 的成功响应（含 Schema 与 Example 值）与 404 的错误响应）：

五、用**解包复用预定义响应（Combine predefined responses and custom ones）

很多场景下，一组"预定义响应"（如 404 Not Found、302 Moved、403 Forbidden）会应用到大量路径操作上，而每个操作又有各自的自定义响应需要叠加。此时可以用 Python 的字典解包技巧把两份配置合并。

先回顾 Python 语法本身：用**dict_to_unpack将一个字典展开到另一个字典字面量中：

old_dict = { "old key": "old value", "second old key": "second old value", } new_dict = {**old_dict, "new key": "new value"}

这里new_dict会包含old_dict的全部键值对，再加上新的键值对：

{ "old key": "old value", "second old key": "second old value", "new key": "new value", }

把它套用到responses上，即可在路径操作中复用预定义响应并叠加个性化配置。官方示例 docs_src/additional_responses/tutorial004_py310.py：

from fastapi import FastAPI from fastapi.responses import FileResponse from pydantic import BaseModel class Item(BaseModel): id: str value: str responses = { 404: {"description": "Item not found"}, 302: {"description": "The item was moved"}, 403: {"description": "Not enough privileges"}, } app = FastAPI() @app.get( "/items/{item_id}", response_model=Item, responses={**responses, 200: {"content": {"image/png": {}}}}, ) async def read_item(item_id: str, img: bool | None = None): if img: return FileResponse("image.png", media_type="image/png") else: return {"id": "foo", "value": "there goes my hero"}

要点：

• responses字典在模块级定义了 404 / 302 / 403 三条预定义响应（只带description，便于多处复用）；
• 装饰器中用{**responses, 200: {...}}展开它，并新增了一条 200 的附加媒体类型配置，二者合并后传给装饰器；
• 若某条自定义响应与预定义响应键冲突（比如都定义了200），后出现的键值会覆盖前者——这是字典解包的天然行为，可按需控制优先级。

更进一步，若多个路由都要共享同一份预定义响应，还可把常量抽取为模块级变量或由公共函数返回，让团队内的路径操作保持一致。从源码角度看，FastAPI 在路由层面也支持响应传播合并——例如在 fastapi/routing.py 的include_router合并逻辑中存在responses={**parent_router.responses, **(responses or {})}这样的模式，说明预定义响应也可以在更上层（如APIRouter）统一定义并向下合并；需要统管一组路由的公共错误响应时，这是一个值得查阅的延伸方向（但注意本仓库APIRouter的responses参数使用细节以源码为准）。

六、附加响应里还能放什么：OpenAPI Response Object 的其他字段

responses中每个响应dict的内容并不限于model、description与example。由于 FastAPI 会把它（去掉model键后）近乎原样合并进 operation 的responses（见 fastapi/openapi/utils.py），任何属于 OpenAPIResponse Object的字段你都可以直接书写，其中包括：

• description：人类可读的响应说明（OpenAPI 强制要求，FastAPI 会如上文所述自动兜底）；
• headers：该响应特有的响应头定义，可配合example或schema说明；
• content：不同媒体类型与其（内联或$ref）JSON Schema 的声明，也是model展开后的归宿；
• links：描述与该响应关联的其它操作（例如 404 后可以"创建该资源"），用于文档化操作间的关系。

关于状态码键还有两个细节值得注意（均有源码佐证）：

1. 数字/字符串键均可：FastAPI 在处理时统一做str(additional_status_code).upper()转换（见 fastapi/openapi/utils.py），因此形如4XX的范围键与default键也可使用；其中"DEFAULT"会被规范化为小写"default"（fastapi/openapi/utils.py）。声明了4XX或default后，FastAPI 会跳过自动追加 422 的步骤，适合你希望自行描述全部校验错误场景的情形；
2. 状态码与响应体兼容性：某些状态码（如 204、304）按 HTTP/OpenAPI 语义不允许携带响应体，因此不能为它们配置model，否则路由构建阶段会直接断言失败（见 fastapi/routing.py）。

想了解某个字段的精确语义与写法边界，可查阅仓库内各类响应相关文档（如 docs/en/docs/advanced/additional-responses.md、docs/en/docs/tutorial/response-model.md、docs/en/docs/tutorial/extra-models.md），并对照本仓库中相应测试 tests/test_tutorial/test_additional_responses/（含 tutorial001～tutorial004 四个用例，逐一断言了响应体与/openapi.json快照）来确认行为。

七、小结：附加响应的三条使用准则

回顾全文，正确使用附加响应需要把握三条准则：

1. 声明与返回分离：responses只负责把附加响应"声明"进 OpenAPI/文档；真正返回时必须在路由函数内直接return JSONResponse(...)/FileResponse(...)等携带状态码与内容，FastAPI 不会替你生成附加响应的实体；
2. model是 FastAPI 语法糖：它不在 OpenAPI 规范内，会由 FastAPI 展开为content → 媒体类型 → schema的$ref引用结构，模型 Schema 统一收纳于components.schemas便于复用与代码生成；
3. 善用合并而非重写：responses可与response_model、status_code共存，附加信息通过deep_dict_update递归合并；跨路由复用时优先用{**predefined, **custom}解包模式组织代码。

按上述方式组织代码后，你的/openapi.json将准确、完整地描述端点的每一种可能返回，Swagger UI 与 ReDoc 中会呈现与实现一一对应的响应契约——这正是 FastAPI"基于标准、面向文档"的 API 设计思路在错误路径与多格式响应上的延伸。

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi