追加のステータスコード¶
🌐 AI と人間による翻訳
この翻訳は、人間のガイドに基づいて AI によって作成されました。🤝
原文の意図を取り違えていたり、不自然な表現になっている可能性があります。🤖
AI LLM をより適切に誘導するのを手伝う ことで、この翻訳を改善できます。
デフォルトでは、 FastAPI は JSONResponse を使ってレスポンスを返し、path operation から返した内容をその JSONResponse の中に入れます。
デフォルトのステータスコード、または path operation で設定したステータスコードが使用されます。
追加のステータスコード¶
メインのステータスコードとは別に追加のステータスコードを返したい場合は、JSONResponse のような Response を直接返し、追加のステータスコードを直接設定できます。
たとえば、item を更新でき、成功時に HTTP ステータスコード 200 "OK" を返す path operation を作りたいとします。
しかし、新しい item も受け付けたいとします。そして、item が以前存在しなかった場合には作成し、HTTP ステータスコード 201「Created」を返します。
これを実現するには、JSONResponse をインポートし、望む status_code を設定して、そこで内容を直接返します。
from typing import Annotated
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: Annotated[str | None, Body()] = None,
size: Annotated[int | None, Body()] = 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)
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
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: str | None = Body(default=None),
size: 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)
Warning
上の例のように Response を直接返すと、それはそのまま返されます。
モデルなどによってシリアライズされません。
必要なデータが含まれていること、そして（JSONResponse を使用している場合）値が有効な JSON であることを確認してください。
技術詳細
from starlette.responses import JSONResponse を使うこともできます。
FastAPI は開発者の利便性のために、fastapi.responses と同じ starlette.responses を提供しています。しかし、利用可能なレスポンスのほとんどは Starlette から直接提供されています。status も同様です。
OpenAPI と API ドキュメント¶
追加のステータスコードとレスポンスを直接返す場合、それらは OpenAPI スキーマ（API ドキュメント）には含まれません。FastAPI には、事前に何が返されるかを知る方法がないからです。
しかし、追加のレスポンス を使ってコード内にドキュメント化できます。