Modèle de réponse FastAPI

Les modèles de réponse sont utilisés pour déclarer la structure de données renvoyée par l'API. En déclarant un modèle de réponse, FastAPI gère automatiquement la validation, la sérialisation et le filtrage des données de sortie, garantissant que le client ne reçoit que les données attendues.


Utilisation des annotations de type de retour

La façon la plus simple est d'annoter directement le type de retour de la fonction d'opération de chemin :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float


@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    # Les données renvoyées seront automatiquement filtrées et validées selon le modèle Item
    return {
        "name": "Foo",
        "description": "Un très bel Item",
        "price": 22.2,
        "secret": "ceci ne doit pas être visible",  # Les champs qui ne sont pas dans Item seront filtrés
    }

FastAPI utilise le modèle de réponse pour effectuer les opérations suivantes :

FonctionnalitésDescription
Vérification des donnéesSi les données renvoyées ne correspondent pas au modèle, cela indique un problème dans le code de l'application.
Filtrage des donnéesNe renvoyer que les champs définis dans le modèle, en filtrant les champs supplémentaires (ceci est important pour la sécurité).
Générer la documentationAfficher la structure de la réponse dans la documentation OpenAPI.
sérialisationUtiliser Pydantic (implémentation Rust) pour convertir efficacement les données en JSON.

paramètre response_model

Lorsque le type de retour est incohérent avec le modèle de réponse, utilisez celui du décorateurresponse_modelParamètres :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()


# Modèle d'entrée (contient le mot de passe)
class UserIn(BaseModel):
    username: str
    password: str
    email: EmailStr


# Modèle de sortie (sans mot de passe)
class UserOut(BaseModel):
    username: str
    email: EmailStr


# La fonction reçoit UserIn, mais la réponse utilise UserOut
@app.post("/users/", response_model=UserOut)
async def create_user(user: UserIn):
    # L'utilisateur renvoyé contient le mot de passe, mais response_model=UserOut exclura le mot de passe.
    return user

C'est un moyen important de protéger les données sensibles. En utilisant des modèles d'entrée et de sortie différents, les champs sensibles tels que les mots de passe n'apparaissent jamais dans les réponses de l'API.


Type de retour et filtrage des données

Héritage de classe recommandé pour implémenter la séparation des modèles d'entrée/sortie, cet exemple permet à la fois à l'éditeur et à mypy de comprendre correctement les types, et permet à FastAPI de filtrer les données :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()


# Modèle utilisateur de base
class BaseUser(BaseModel):
    username: str
    email: EmailStr


# Modèle d'entrée : hérite du modèle de base, ajoute un champ mot de passe
class UserIn(BaseUser):
    password: str


@app.post("/users/")
async def create_user(user: UserIn) -> BaseUser:
    # L'annotation de type de retour est BaseUser, et FastAPI filtrera le champ mot de passe.
    # L'éditeur et mypy sont également satisfaits, car UserIn est une sous-classe de BaseUser
    return user

En excluant les valeurs par défaut non définies

Utilisationresponse_model_exclude_unset=True, ne renvoyer que les champs qui ont réellement des valeurs définies :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float = 10.5
    tags: list[str] = []


items = {
    "foo": {"name": "Foo", "price": 50.2},
    "bar": {"name": "Bar", "description": "Les barmans", "price": 62, "tax": 20.2},
    "baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}


@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
    return items[item_id]

Comparaison des réponses pour différents item_id :

item_idresponseDescription
foo{"name": "Foo", "price": 50.2}Seuls les champs explicitement définis sont renvoyés, en omettant les valeurs par défaut.
bar{"name": "Bar", "description": "...", "price": 62, "tax": 20.2}Tous les champs ont des valeurs réelles, donc tous sont renvoyés

Paramètres de filtre associés :

ParamètreDescription
response_model_exclude_unsetExclure les champs avec des valeurs non définies
response_model_exclude_defaultsExclure les champs avec des valeurs par défaut
response_model_exclude_noneExclure les champs avec la valeur None

Inclure/exclure des champs spécifiques

Utilisationresponse_model_includeetresponse_model_excludeChamps de sortie précis :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float = 10.5


# contient name et description
@app.get("/items/{item_id}", response_model=Item, response_model_include={"name", "description"})
async def read_item_name(item: str):
    return items[item_id]


# Exclure la taxe
@app.get("/items/{item}/no-tax", response_model=Item, response_model_exclude={"tax"})
async def read_item_no_tax(item_id: str):
    return items[item_id]

Bien queresponse_model_includeetresponse_model_excludePermet de filtrer rapidement les champs, mais il est recommandé d'utiliser plutôt plusieurs classes de modèle, car elles ne peuvent pas supprimer les champs exclus de la documentation OpenAPI.


Résumé

  • Utilisationresponse_modelLes annotations de type de paramètre ou de retour déclarent le modèle de réponse.
  • Le rôle central du modèle de réponse est le filtrage des données, protégeant les données sensibles contre toute fuite.
  • Utilisez des modèles différents pour l'entrée et la sortie afin de garantir que des champs tels que les mots de passe n'apparaissent pas dans la réponse.
  • response_model_exclude_unsetRenvoyer uniquement les champs réellement définis
  • Il est recommandé d'utiliser l'héritage de modèle + les annotations de type de retour plutôt queresponse_model_include/exclude
autres extensions