fastapi/docs/ja/docs/tutorial/body-fields.md

ボディ - フィールド

QueryやPath、Bodyを使って path operation関数 のパラメータに追加のバリデーションやメタデータを宣言するのと同じように、PydanticのFieldを使ってPydanticモデルの内部でバリデーションやメタデータを宣言することができます。

Fieldのインポート

まず、以下のようにインポートします:

{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[4] *}

/// warning | 注意

Fieldは他の全てのもの（Query、Path、Bodyなど）とは違い、fastapiからではなく、pydanticから直接インポートされていることに注意してください。

///

モデルの属性の宣言

以下のようにFieldをモデルの属性として使用することができます:

{* ../../docs_src/body_fields/tutorial001_an_py310.py hl[11:14] *}

FieldはQueryやPath、Bodyと同じように動作し、全く同様のパラメータなどを持ちます。

/// note | 技術詳細

実際には次に見るQueryやPathなどは、共通のParamクラスのサブクラスのオブジェクトを作成しますが、それ自体はPydanticのFieldInfoクラスのサブクラスです。

また、PydanticのFieldはFieldInfoのインスタンスも返します。

BodyはFieldInfoのサブクラスのオブジェクトを直接返すこともできます。そして、他にもBodyクラスのサブクラスであるものがあります。

fastapiからQueryやPathなどをインポートする場合、これらは実際には特殊なクラスを返す関数であることに注意してください。

///

/// tip | 豆知識

型、デフォルト値、Fieldを持つ各モデルの属性が、PathやQuery、Bodyの代わりにFieldを持つ、path operation 関数のパラメータと同じ構造になっていることに注目してください。

///

追加情報の追加

追加情報はFieldやQuery、Bodyなどで宣言することができます。そしてそれは生成されたJSONスキーマに含まれます。

後に例を用いて宣言を学ぶ際に、追加情報を追加する方法を学べます。

/// warning | 注意

Fieldに渡された追加のキーは、結果として生成されるアプリケーションのOpenAPIスキーマにも含まれます。 これらのキーは必ずしもOpenAPI仕様の一部であるとは限らないため、例えばOpenAPI validatorなどの一部のOpenAPIツールは、生成されたスキーマでは動作しない場合があります。

///

まとめ

PydanticのFieldを使用して、モデルの属性に追加のバリデーションやメタデータを宣言することができます。

追加のキーワード引数を使用して、追加のJSONスキーマのメタデータを渡すこともできます。