読み方のヒント

矢印ボタン(または ← → キー)でページを移動できます。

第5節 API仕様の読み方

5.2 失敗の応答を仕様に書く

自動で作られた仕様の422には、入力の形の誤りの形だけが載っています。店の規則の違反の形(code と message)は載っていません。応答のモデルを定義し、responses で仕様に加えます。

class ErrorDetail(BaseModel):
    code: str
    message: str


class ErrorOut(BaseModel):
    detail: ErrorDetail


@app.post(
    "/reservations",
    status_code=201,
    response_model=ReservationOut,
    responses={422: {"model": ErrorOut, "description": "入力の形や店の規則に合わない"}},
)

/docs の422の欄に、code と message の形と、説明の文が表示されます。

code に使う値は、一覧にしてAPIを使う人に渡します。

code意味
closed_day受け取りが水曜日
outside_hours受け取りの時刻が営業時間外
deadline_passed受け取りの前日20:00を過ぎている
too_many_items合計が11個以上
duplicate_product同じ商品が2行以上ある
unknown_product存在しない商品ID
not_reservable予約できない商品

画面を作る人は、code を見て表示を変えられます。たとえば deadline_passed なら、受け取り日を選び直す欄を目立たせます。message は、そのまま画面に表示できる文です。

解答例

{"name": "田中", "pickupAt": "2026-11-02T08:00:00+09:00", "items": [{"productId": "p001", "quantity": 1}, {"productId": "p002", "quantity": 2}]} です。11月2日は月曜日、8:00は営業時間内、締切の11月1日20:00より前、食パンとクロワッサンは予約でき、合計は3個です。実際に送る日が違うときは、締切に間に合う受け取り日に変えます。

19 / 20