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に含まれないフィールドはフィルタリングされます
}
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
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
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]
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]
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