FastAPI レスポンスモデル

レスポンスモデルは、APIが返すデータ構造を宣言するために使用します。レスポンスモデルを宣言することで、FastAPIは出力データの検証、シリアライゼーション、フィルタリングを自動的に行い、クライアントが期待するデータのみを受け取ることを保証します。


戻り値の型注釈を使用する

最も簡単な方法は、パス操作関数の戻り値の型を直接注釈することです:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float


@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    # 返されるデータは自動的にItemモデルに従ってフィルタリングおよび検証されます
    return {
        "name": "Foo",
        "description": "A very nice Item",
        "price": 22.2,
        "secret": "this should not be visible",  # Itemに含まれないフィールドはフィルタリングされます
    }

FastAPIはレスポンスモデルを使用して次の作業を行います:

機能説明
データ検証返されたデータがモデルと一致しない場合、アプリケーションコードに問題があることを示しています
データフィルタリングモデルで定義されたフィールドのみを返し、余分なフィールドをフィルタリングします(これはセキュリティ上重要です)
ドキュメント生成OpenAPIドキュメントにレスポンス構造を表示します
シリアライゼーションPydantic(Rust実装)を使用して、データを効率的にJSONに変換します

response_model パラメータ

戻り値の型がレスポンスモデルと一致しない場合は、デコレータのresponse_modelパラメータ:

例

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()


# 入力モデル(パスワードを含む)
class UserIn(BaseModel):
    username: str
    password: str
    email: EmailStr


# 出力モデル(パスワードを含まない)
class UserOut(BaseModel):
    username: str
    email: EmailStr


# 関数はUserInを受け取るが、レスポンスはUserOutを使用する
@app.post("/users/", response_model=UserOut)
async def create_user(user: UserIn):
    # 返されるuserにはパスワードが含まれるが、response_model=UserOutがパスワードをフィルタリングする
    return user

これは機密データを保護する重要な手段です。異なる入力モデルと出力モデルを使用することで、パスワードなどの機密フィールドがAPIレスポンスに決して現れないようにします。


戻り値の型とデータフィルタリング

入力/出力モデルの分離にはクラス継承を使用することをお勧めします。これにより、エディタやmypyが型を正しく理解できるだけでなく、FastAPIがデータをフィルタリングできるようになります:

例

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()


# 基本ユーザーモデル
class BaseUser(BaseModel):
    username: str
    email: EmailStr


# 入力モデル:基本モデルを継承し、パスワードフィールドを追加
class UserIn(BaseUser):
    password: str


@app.post("/users/")
async def create_user(user: UserIn) -> BaseUser:
    # 戻り値の型注釈がBaseUserの場合、FastAPIはpasswordフィールドをフィルタリングする
    # エディタとmypyも満足する。UserInはBaseUserのサブクラスだからです
    return user

未設定のデフォルト値を除外する

使用しresponse_model_exclude_unset=True、実際に設定された値のフィールドのみを返します:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float = 10.5
    tags: list[str] = []


items = {
    "foo": {"name": "Foo", "price": 50.2},
    "bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
    "baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}


@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
    return items[item_id]

異なる item_id のレスポンス比較:

item_idレスポンス説明
foo{"name": "Foo", "price": 50.2}明示的に設定されたフィールドのみを返し、デフォルト値を省略します
bar{"name": "Bar", "description": "...", "price": 62, "tax": 20.2}すべてのフィールドに実際の値があるため、すべて返されます

関連するフィルタリングパラメータ:

パラメータ説明
response_model_exclude_unset未設定の値のフィールドを除外
response_model_exclude_defaults値がデフォルト値であるフィールドを除外
response_model_exclude_none値が None のフィールドを除外

特定フィールドの包含/除外

使用しresponse_model_includeとresponse_model_exclude出力フィールドを正確に制御します:

例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float = 10.5


# name と description のみを含む
@app.get("/items/{item_id}", response_model=Item, response_model_include={"name", "description"})
async def read_item_name(item_id: str):
    return items[item_id]


# tax を除外
@app.get("/items/{item_id}/no-tax", response_model=Item, response_model_exclude={"tax"})
async def read_item_no_tax(item_id: str):
    return items[item_id]

この方法はresponse_model_includeとresponse_model_excludeフィールドをすばやくフィルタリングできますが、除外されたフィールドをOpenAPIドキュメントから削除できないため、複数のモデルクラスを使用することをお勧めします。


まとめ

  • 使用してresponse_modelパラメータまたは戻り値の型注釈でレスポンスモデルを宣言します
  • レスポンスモデルの中心的な役割はデータフィルタリングであり、機密データが漏洩しないように保護します
  • 入力と出力に異なるモデルを使用して、パスワードなどのフィールドがレスポンスに現れないようにします
  • response_model_exclude_unset実際に設定されたフィールドのみを返します
  • モデル継承 + 戻り値の型注釈の使用を推奨します。response_model_include/exclude
その他の拡張機能ではなく。