Do czego służy response_model?

Question

Accepted Answer

Parametr **`response_model`** deklaruje kształt odpowiedzi endpoint'u. FastAPI używa go do **walidacji, filtrowania i serializacji** zwracanych danych — oraz do dokumentowania odpowiedzi w dokumentacji API. Jego najważniejsza rola: zapewnienie, że exponujesz tylko zamierzone pola (np. nigdy nie wyciękaj hasła).

## Problem: wyciek wrażliwych pól

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

## Rozwiązanie: oddzielny model odpowiedzi

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

Z `response_model=UserOut`, FastAPI bierze to, co zwracasz, i **filtruje to** do tylko pól zdeklarowanych w `UserOut` — więc hasło (i wszelkie inne dodatkowe pola) zostaje usunięte z odpowiedzi, nawet jeśli zwróciłeś pełny obiekt.

## Co robi 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
```

## Nowoczesna alternatywa: adnotacja typu zwracanego

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

## Dlaczego to ważne

`response_model` jest ważny zarówno dla **bezpieczeństwa** jak i czystego projektowania API.

Szczególnie ważne jest uniemożliwienie niezamierzonego wycieku danych — poprzez dokładne zadeklarowanie, które pola powinna zawierać odpowiedź, FastAPI filtruje wszystko inne (takie jak hasze haseł, flagi wewnętrzne lub tokeny) nawet jeśli kod zwróci pełny obiekt bazy danych, eliminując powszechną i poważną lukę w zabezpieczeniach.

Poza tym waliduje odpowiedzi względem zadeklarowanego schematu (łapląc błędy, w których zwracasz zły kształt), zapewnia prawidłową serializację i dokumentuje odpowiedź w automatycznie generowanej dokumentacji API.

Wzorzec używania oddzielnych modeli wejścia i wyjścia (gdzie `response_model` kontroluje, co jest exponowane) jest najlepszą praktyką dla bezpiecznych, dobrze zdefiniowanych API, co czyni to ważną wiedzą dla każdego endpoint'u zwracającego dane.