response_model は何のためのものですか？

Question

Accepted Answer

**`response_model`** パラメータはエンドポイントのレスポンス形状を宣言します。FastAPI はそれを使用して返されたデータを **検証、フィルター、シリアル化** し、API ドキュメントにレスポンスを文書化します。最も重要な役割は、意図したフィールドのみを公開することを保証することです（例えば、パスワードが決してリークしないようにする）。

## 問題: 機密フィールドのリーク

```python
class User(BaseModel):
    name: str
    email: str
    password: str        # ⚠️ should NEVER be in the response!

@app.get("/users/{id}")
def get_user(id: int) -> User:
    return db.get_user(id)   # returning the full object would expose the password
```

## 解決策: 別のレスポンスモデル

```python
class UserOut(BaseModel):    # the SAFE public shape — no password
    name: str
    email: str

@app.get("/users/{id}", response_model=UserOut)
def get_user(id: int):
    return db.get_user(id)   # returns a full user, but FastAPI FILTERS it to UserOut
# response → { "name": "...", "email": "..." }  — password stripped automatically
```

`response_model=UserOut` を使用すると、FastAPI は返された内容を受け取り、`UserOut` で宣言されたフィールド **だけにフィルター** します — したがって、パスワード（および他の余分なフィールド）は、完全なオブジェクトを返した場合でもレスポンスから削除されます。

## response_model の機能

```text
✓ FILTERS the output to only the declared fields (key for hiding sensitive data)
✓ VALIDATES that your response matches the declared schema (catches mistakes)
✓ SERIALIZES the data to JSON correctly
✓ DOCUMENTS the response shape in the OpenAPI/Swagger docs
```

## 最新の代替手段: 戻り値型アノテーション

```python
@app.get("/users/{id}")
def get_user(id: int) -> UserOut:    # the -> return type works like response_model
    return db.get_user(id)
# response_model_exclude_unset=True → omit fields not explicitly set
```

## なぜ重要なのか

`response_model` は **セキュリティ** とクリーンな API 設計の両方に重要です。

その最も重要な役割は、意図しないデータリークを防ぐことです — レスポンスに含まれるべきフィールドを正確に宣言することで、FastAPI は他のすべて（パスワードハッシュ、内部フラグ、トークンなど）をフィルター処理します。これはコードが完全なデータベースオブジェクトを返す場合でも行われ、一般的で深刻な脆弱性を排除します。

それ以外にも、宣言されたスキーマに対してレスポンスを検証し（間違った形を返すバグを検出）、正しいシリアル化を保証し、自動生成される API ドキュメントにレスポンスを文書化します。

入力モデルと出力モデルを分離して使用するパターン（`response_model` が何が公開されるかを制御）は、安全でよく定義された API のベストプラクティスであり、データを返すあらゆるエンドポイントに対してこの知識が重要です。