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 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és | Description |
|---|---|
| Vérification des données | Si 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ées | Ne 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 documentation | Afficher la structure de la réponse dans la documentation OpenAPI. |
| sérialisation | Utiliser 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 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 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 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_id | response | Description |
|---|---|---|
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ètre | Description |
|---|---|
response_model_exclude_unset | Exclure les champs avec des valeurs non définies |
response_model_exclude_defaults | Exclure les champs avec des valeurs par défaut |
response_model_exclude_none | Exclure les champs avec la valeur None |
Inclure/exclure des champs spécifiques
Utilisationresponse_model_includeetresponse_model_excludeChamps de sortie précis :
Exemple
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 que
response_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é
- Utilisation
response_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 que
response_model_include/exclude