Для чего нужен response_model?

Question

Accepted Answer

Параметр **`response_model`** объявляет форму ответа endpoint'а. 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, что делает эти знания важными для любого endpoint'а, возвращающего данные.