OpenAPI 中的额外响应¶
警告
这是一个相当高级的主题。
如果您刚开始使用 FastAPI，您可能不需要它。
您可以声明额外的响应，包括额外的状态码、媒体类型、描述等。
这些额外的响应将包含在 OpenAPI 模式中，因此它们也会出现在 API 文档中。
但对于这些额外的响应，您必须确保您直接返回一个 Response（例如 JSONResponse），包括您的状态码和内容。
带 model 的额外响应¶
您可以将参数 responses 传递给您的路径操作装饰器。
它接收一个 dict：键是每个响应的状态码（如 200），值是包含每个响应信息的 dict。
这些响应 dict 中的每一个都可以有一个键 model，包含一个 Pydantic 模型，就像 response_model 一样。
FastAPI 将获取该模型，生成其 JSON 模式，并将其包含在 OpenAPI 中的正确位置。
例如，要声明另一个响应，状态码为 404，Pydantic 模型为 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"})
注意
请记住，您必须直接返回 JSONResponse。
信息
model 键不是 OpenAPI 的一部分。
FastAPI 将从那里获取 Pydantic 模型，生成 JSON 模式，并将其放在正确的位置。
正确的位置是
- 在键
content中，它的值是另一个 JSON 对象 (dict)，其中包含- 一个带媒体类型的键，例如
application/json，它的值是另一个 JSON 对象，其中包含- 一个键
schema，它的值为模型的 JSON 模式，这是正确的位置。- FastAPI 在这里添加了一个引用，指向 OpenAPI 模式中另一个位置的全局 JSON 模式，而不是直接包含它。这样，其他应用程序和客户端可以直接使用这些 JSON 模式，提供更好的代码生成工具等。
- 一个键
- 一个带媒体类型的键，例如
为此路径操作生成的 OpenAPI 响应将是
{
"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"
}
}
}
}
}
}
这些模式引用了 OpenAPI 模式中另一个位置
{
"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"
}
}
}
}
}
}
}
主响应的额外媒体类型¶
您可以使用相同的 responses 参数为同一个主响应添加不同的媒体类型。
例如，您可以添加一个额外的媒体类型 image/png，声明您的路径操作可以返回一个 JSON 对象（媒体类型为 application/json）或一个 PNG 图像
from typing import Union
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: Union[bool, None] = None):
if img:
return FileResponse("image.png", media_type="image/png")
else:
return {"id": "foo", "value": "there goes my hero"}
注意
注意，您必须使用 FileResponse 直接返回图像。
信息
除非您在 responses 参数中显式指定不同的媒体类型，否则 FastAPI 将假设响应与主响应类具有相同的媒体类型（默认值为 application/json）。
但是，如果您为自定义响应类指定了 None 作为其媒体类型，那么 FastAPI 将使用 application/json 作为任何具有关联模型的额外响应的媒体类型。
组合信息¶
您还可以组合来自多个位置的响应信息，包括 response_model、status_code 和 responses 参数。
您可以声明一个 response_model，使用默认状态码 200（或者您需要的话使用自定义状态码），然后在 responses 中直接在 OpenAPI 模式中为同一个响应声明额外的信息。
FastAPI 会保留 responses 中的附加信息，并将其与模型中的 JSON Schema 相结合。
例如，您可以声明一个状态码为 404 的响应，该响应使用 Pydantic 模型并具有自定义的 description。
以及一个状态码为 200 的响应，该响应使用您的 response_model，但包含一个自定义的 example
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"})
所有这些信息都会被合并并包含在您的 OpenAPI 中，并显示在 API 文档中。
组合预定义响应和自定义响应¶
您可能希望有一些预定义的响应适用于多个路径操作，但您想将它们与每个路径操作所需的自定义响应结合起来。
对于这些情况，您可以使用 Python 中的“解包”dict 的技术，使用 **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",
}
您可以使用这种技术在您的路径操作中重用一些预定义的响应，并将它们与额外的自定义响应结合起来。
例如
from typing import Union
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: Union[bool, None] = None):
if img:
return FileResponse("image.png", media_type="image/png")
else:
return {"id": "foo", "value": "there goes my hero"}
有关 OpenAPI 响应的更多信息¶
要查看您可以在响应中包含哪些内容，您可以查看 OpenAPI 规范中的这些部分。
- OpenAPI 响应对象，它包含
响应对象。 - OpenAPI 响应对象，您可以在
responses参数中的每个响应中直接包含来自此对象的内容。包括description、headers、content（在此内部声明不同的媒体类型和 JSON Schema）以及links。