追加のステータスコード

デフォルトでは、 FastAPI は JSONResponse を使ってレスポンスを返します。その JSONResponse の中には、 path operation が返した内容が入ります。

それは、デフォルトのステータスコードか、 path operation でセットしたものを利用します。

追加のステータスコード

メインのステータスコードとは別に、他のステータスコードを返したい場合は、Response (JSONResponse など) に追加のステータスコードを設定して直接返します。

例えば、itemを更新し、成功した場合は200 "OK"のHTTPステータスコードを返す path operation を作りたいとします。

しかし、新しいitemも許可したいです。itemが存在しない場合は、それらを作成して201 "Created"を返します。

これを達成するには、 JSONResponse をインポートし、 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 を明示的に返す場合、それは直接返されます。

モデルなどはシリアライズされません。

必要なデータが含まれていることや、値が有効なJSONであること (JSONResponse を使う場合) を確認してください。

技術詳細

from starlette.responses import JSONResponse を利用することもできます。

FastAPI は fastapi.responses と同じ starlette.responses を、開発者の利便性のために提供しています。しかし有効なレスポンスはほとんどStarletteから来ています。 status についても同じです。

OpenAPIとAPIドキュメント

ステータスコードとレスポンスを直接返す場合、それらはOpenAPIスキーマ (APIドキュメント) には含まれません。なぜなら、FastAPIは何が返されるのか事前に知ることができないからです。

しかし、 Additional Responses を使ってコードの中にドキュメントを書くことができます。