3.0 KiB
スキーマの追加 - 例
JSON Schemaに追加する情報を定義することができます。
一般的なユースケースはこのドキュメントで示されているようにexampleを追加することです。
JSON Schemaの追加情報を宣言する方法はいくつかあります。
Pydanticのschema_extra
Pydanticのドキュメント: スキーマのカスタマイズで説明されているように、Configとschema_extraを使ってPydanticモデルの例を宣言することができます:
{!../../../docs_src/schema_extra_example/tutorial001.py!}
その追加情報はそのまま出力され、JSON Schemaに追加されます。
Fieldの追加引数
後述するField、Path、Query、Bodyなどでは、任意の引数を関数に渡すことでJSON Schemaの追加情報を宣言することもできます:
{!../../../docs_src/schema_extra_example/tutorial002.py!}
!!! warning "注意" これらの追加引数が渡されても、文書化のためのバリデーションは追加されず、注釈だけが追加されることを覚えておいてください。
Bodyの追加引数
追加情報をFieldに渡すのと同じように、Path、Query、Bodyなどでも同じことができます。
例えば、Bodyにボディリクエストのexampleを渡すことができます:
{!../../../docs_src/schema_extra_example/tutorial003.py!}
ドキュメントのUIの例
上記のいずれの方法でも、/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に追加される独自の追加情報を追加することができます。