Para que serve o response_model?

Question

Accepted Answer

O parâmetro **`response_model`** declara a forma da resposta de um endpoint. O FastAPI o usa para **validar, filtrar e serializar** os dados retornados — e para documentar a resposta nos docs da API. Seu trabalho mais importante: garantir que você exponha apenas os campos pretendidos (por exemplo, nunca vaze uma senha).

## O problema: vazamento de campos sensíveis

```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
```

## A solução: um modelo de resposta separado

```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
```

Com `response_model=UserOut`, o FastAPI pega o que você retorna e **filtra** para apenas os campos declarados em `UserOut` — portanto, a senha (e quaisquer outros campos extras) é removida da resposta, mesmo que você tenha retornado o objeto completo.

## O que response_model faz

```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
```

## Alternativa moderna: a anotação de tipo de retorno

```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
```

## Por que isso importa

`response_model` é importante tanto para **segurança** quanto para design limpo de API.

Seu papel mais crítico é prevenir vazamentos acidentais de dados — ao declarar exatamente quais campos a resposta deve conter, o FastAPI filtra tudo o resto (como hashes de senha, sinalizadores internos ou tokens) mesmo que seu código retorne um objeto de banco de dados completo, eliminando uma vulnerabilidade comum e séria.

Além disso, ele valida suas respostas contra um esquema declarado (detectando bugs onde você retorna a forma errada), garante serialização correta e documenta a resposta nos docs da API gerados automaticamente.

O padrão de usar modelos de entrada e saída separados (com `response_model` controlando o que é exposto) é uma prática recomendada para APIs seguras e bem definidas, tornando este conhecimento importante para qualquer endpoint que retorne dados.