スキーマの追加 - 例¶

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

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

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

Pydanticの`schema_extra`¶

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

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "name": "Foo",
                    "description": "A very nice Item",
                    "price": 35.4,
                    "tax": 3.2,
                }
            ]
        }
    }


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

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

`Field`の追加引数¶

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

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(examples=["Foo"])
    description: Union[str, None] = Field(default=None, examples=["A very nice Item"])
    price: float = Field(examples=[35.4])
    tax: Union[float, None] = Field(default=None, examples=[3.2])


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

注意

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

`Body`の追加引数¶

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

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

from typing import Union

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None


@app.put("/items/{item_id}")
async def update_item(
    item_id: int,
    item: Item = Body(
        examples=[
            {
                "name": "Foo",
                "description": "A very nice Item",
                "price": 35.4,
                "tax": 3.2,
            }
        ],
    ),
):
    results = {"item_id": item_id, "item": item}
    return results

ドキュメントの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に追加される独自の追加情報を追加することができます。