Na co slouží response_model?

Question

Accepted Answer

Parametr **`response_model`** deklaruje tvar odpovědi koncového bodu. FastAPI jej používá k **ověření, filtrování a serializaci** vrácených dat — a k dokumentaci odpovědi v API dokumentaci. Jeho nejdůležitější úkol: zajistit, aby jste vystavili pouze zamýšlená pole (např. nikdy neunikla hesla).

## Problém: úniky citlivých polí

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

## Řešení: oddělený response model

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

S `response_model=UserOut` FastAPI vezme cokoli, co vrátíte, a **filtruje to** pouze na pole deklarovaná v `UserOut` — takže heslo (a jakákoli další extra pole) je z odpovědi odstraněno, i když jste vrátili úplný objekt.

## Co response_model dělá

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

## Moderní alternativa: anotace typu návratu

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

## Proč je to důležité

`response_model` je důležitý pro **bezpečnost** i čistý design API.

Jeho nejkritičtější role spočívá v prevenci náhodných úniků dat — deklarací přesně toho, která pole má odpověď obsahovat, FastAPI filtruje vše ostatní (jako haše hesel, interní příznaky nebo tokeny), i když váš kód vrací úplný databázový objekt, čímž eliminuje běžnou a vážnou zranitelnost.

Beyond toho ověřuje vaše odpovědi proti deklarovanému schématu (odhaluje chyby, kdy vrátíte špatný tvar), zajišťuje správnou serializaci a dokumentuje odpověď v automaticky generované API dokumentaci.

Vzor použití oddělených vstupních a výstupních modelů (s `response_model` kontrolujícím, co je vystaveno) je osvědčená praxe pro bezpečné, dobře definované API, což činí tyto znalosti důležitými pro jakýkoli koncový bod, který vrací data.