附加状态码

FastAPI 默认使用 JSONResponse 返回响应，路径操作返回的内容会放在 JSONResponse 里。

并使用默认状态码或在路径操作中设置的状态码。

附加状态码

返回主状态码之外的附加状态码时，要直接返回 JSONResponse 等 Response，并直接设置状态码。

例如，有一个更新商品（item）的路径操作，更新成功时要返回 HTTP 状态码 - 200 OK。

但该路径操作要能接受新的商品。商品不存在时，还要能自动创建新商品并返回 HTTP 状态码 - 201 Created。

为此，要导入 JSONResponse，然后直接返回 content，并设置 status_code。

from typing import Union

from fastapi import Body, FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

items = {"foo": {"name": "Fighters", "size": 6}, "bar": {"name": "Tenders", "size": 3}}


@app.put("/items/{item_id}")
async def upsert_item(
    item_id: str,
    name: Union[str, None] = Body(default=None),
    size: Union[int, None] = Body(default=None),
):
    if item_id in items:
        item = items[item_id]
        item["name"] = name
        item["size"] = size
        return item
    else:
        item = {"name": name, "size": size}
        items[item_id] = item
        return JSONResponse(status_code=status.HTTP_201_CREATED, content=item)

警告

直接返回 Response 时，如上例会直接返回响应。

FastAPI 不使用模型序列化该响应。

此时，要确保数据完整，如果使用的是 JSONResponse，还要确保返回值是有效的 JSON 数据。

技术细节

您还可以使用 from starlette.responses import JSONResponse。　

FastAPI 的 fastapi.responses 与 starlette.responses 一样，但绝大多数可用的响应都直接继承自 Starlette。status 也一样。

OpenAPI 和 API 文档

OpenAPI 概图（API 文档）不包含直接返回的状态码和响应，因为 FastAPI 无法预判返回的内容。

但附加响应 可在代码中实现存档操作。