スキーマの追加 - 例

JSON Schemaに追加する情報を定義することができます。

一般的なユースケースはこのドキュメントで示されているようにexampleを追加することです。

JSON Schemaの追加情報を宣言する方法はいくつかあります。

Pydanticの`schema_extra`

Pydanticのドキュメント: スキーマのカスタマイズで説明されているように、Configとschema_extraを使ってPydanticモデルの例を宣言することができます:

{!../../docs_src/schema_extra_example/tutorial001.py!}

その追加情報はそのまま出力され、JSON Schemaに追加されます。

後述するField、Path、Query、Bodyなどでは、任意の引数を関数に渡すことでJSON Schemaの追加情報を宣言することもできます:

{!../../docs_src/schema_extra_example/tutorial002.py!}

/// warning | "注意"

これらの追加引数が渡されても、文書化のためのバリデーションは追加されず、注釈だけが追加されることを覚えておいてください。

///

追加情報をFieldに渡すのと同じように、Path、Query、Bodyなどでも同じことができます。

例えば、Bodyにボディリクエストのexampleを渡すことができます:

{!../../docs_src/schema_extra_example/tutorial003.py!}

上記のいずれの方法でも、/docsの中では以下のようになります:

example と examplesについて...

JSON Schemaの最新バージョンではexamplesというフィールドを定義していますが、OpenAPIはexamplesを持たない古いバージョンのJSON Schemaをベースにしています。

そのため、OpenAPIでは同じ目的のためにexampleを独自に定義しており（examplesではなくexampleとして）、それがdocs UI（Swagger UIを使用）で使用されています。

つまり、exampleはJSON Schemaの一部ではありませんが、OpenAPIの一部であり、それがdocs UIで使用されることになります。

同じように、フロントエンドのユーザーインターフェースなどをカスタマイズするために、各モデルのJSON Schemaに追加される独自の追加情報を追加することができます。