fastapi/docs/ja/docs/tutorial/query-param-models.md

クエリパラメータモデル

もし関連する複数のクエリパラメータから成るグループがあるなら、それらを宣言するために、Pydanticモデルを作成できます。

こうすることで、複数の場所でそのモデルを再利用でき、バリデーションやメタデータを、すべてのパラメータに対して一度に宣言できます。😎

/// note | 備考

この機能は、FastAPIのバージョン 0.115.0 からサポートされています。🤓

///

Pydanticモデルを使ったクエリパラメータ

必要なクエリパラメータをPydanticモデルで宣言し、さらに、そのパラメータを Query として宣言しましょう:

{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}

FastAPIは、リクエストのクエリパラメータからそれぞれのフィールドのデータを抽出し、定義したPydanticモデルを提供します。

ドキュメントの確認

対話的APIドキュメント /docs でクエリパラメータを確認できます:

余分なクエリパラメータを禁止する

特定の（あまり一般的ではないかもしれない）ユースケースで、受け取りたいクエリパラメータを制限したい場合があります。

Pydanticのモデル設定を使って、あらゆる extra フィールドを forbid にできます。

{* ../../docs_src/query_param_models/tutorial002_an_py310.py hl[10] *}

もしクライアントがクエリパラメータとして余分なデータを送ろうとすると、エラーレスポンスが返されます。

例えば、クライアントがクエリパラメータ tool に、値 plumbus を設定して送ろうとすると:

https://example.com/items/?limit=10&tool=plumbus

クエリパラメータ tool が許可されていないことを伝えるエラーレスポンスが返されます。

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["query", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus"
        }
    ]
}

まとめ

FastAPIでは、クエリパラメータを宣言するために、Pydanticモデルを使用できます。😎

/// tip | 豆知識

ネタバレ注意: Pydanticモデルはクッキーやヘッダーの宣言にも使用できますが、その内容については後のチュートリアルで学びます。🤫

///