Validation des paramètres de requête FastAPI

FastAPI vous permet de déclarer des règles de validation et des métadonnées supplémentaires pour les paramètres de requête, telles que des limites de longueur de chaîne, la correspondance regex, etc. Grâce à cette fonctionnalitéQueryetAnnotated, vous pouvez améliorer la validation des paramètres sans modifier la logique de la fonction.


Validation de base

L'exemple suivant concerne les paramètres de requêteqAjouter une limite de longueur maximale:

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    # Utiliser Annotated + Query pour ajouter une validation
    q: Annotated[str | None, Query(max_length=50)] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Explication du code :

PartieDescription
Annotated[str | None, ...]Annotations de type, significationqPeut être une chaîne de caractères ou None
Query(max_length=50)Règles de validation,qLa longueur maximale est de 50 caractères
= NoneValeur par défaut, ce qui rend le paramètre facultatif

FastAPI recommande d'utiliserAnnotatedDéclarer la validation d'une manière, plutôt que d'utiliserQuerycomme valeur par défaut. Parce queAnnotatedDans cette approche, la valeur par défaut de la fonction est la vraie valeur par défaut, ce qui est plus intuitif en Python et mieux pris en charge par les éditeurs et les outils de vérification de type.


Ajout de validations supplémentaires

Vous pouvez ajouter plusieurs règles de validation simultanément :

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    # Limiter également la longueur minimale, la longueur maximale et l'expression régulière
    q: Annotated[str | None, Query(min_length=3, max_length=50, pattern="^fixedquery$")] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Paramètres de validation de chaîne :

ParamètreTypeDescription
min_lengthintLongueur minimale
max_lengthintLongueur maximale
patternstrCorrespondance d'expression régulière

Expression régulière^fixedquery$Signification :

  • ^-- Doit commencer par les caractères suivants
  • fixedquery-- La valeur doit être exactement égale àfixedquery
  • $-- Fin ici ; aucun autre caractère ne peut suivre.

Validation avec des valeurs par défaut

Vous pouvez définir à la fois une valeur par défaut et des règles de validation pour un paramètre de requête :

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    # La valeur par défaut est "fixedquery", et la longueur minimale est 3
    q: Annotated[str, Query(min_length=3)] = "fixedquery",
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Valeur par défaut de tout type (y compris non-Nonevalue) rendra le paramètre optionnel. Sans valeur par défaut et sansQuery(default=...)les paramètres sont obligatoires.


Paramètre obligatoire

UtilisationQuery, si vous ne déclarez pas de valeur par défaut, le paramètre est obligatoire :

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    # Aucune valeur = None, donc q est un paramètre obligatoire.
    q: Annotated[str, Query(min_length=3)],
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    results.update({"q": q})
    return results

Obligatoire mais peut être None

Parfois, vous avez besoin que le client passe une valeur, mais la valeur peut êtreNone:

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    # Le client doit fournir le paramètre q, mais la valeur peut être None
    q: Annotated[str | None, Query(min_length=3)],
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Liste de paramètres de requête / valeurs multiples

UtilisationQueryVous pouvez déclarer des paramètres de requête qui reçoivent plusieurs valeurs :

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    # q peut apparaître plusieurs fois dans l'URL, et les valeurs seront collectées sous forme de liste
    q: Annotated[list[str] | None, Query()] = Aucune,
):
    query_items = {"q": q}
    return query_items

Visitezhttp://127.0.0.1:8000/items/?q=foo&q=bar, renvoie :

{"q": ["foo", "bar"]}

Pour déclarer le type commelistparamètres de requête, vous devez utiliser explicitementQuery(), sinon FastAPI l'interprétera comme le corps de la requête.


Déclarer des métadonnées

QueryIl prend également en charge l'ajout de métadonnées aux paramètres ; ces informations apparaîtront dans la documentation de l'API :

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(
        title="query string",           # Titre du paramètre
        description="Chaîne de requête utilisée pour filtrer les produits",  # Description du paramètre
        min_length=3,
        max_length=50,
        alias="item-query",    # Alias pour le nom du paramètre dans l'URL
        deprecated=True,       # Marquer comme obsolète
    )] = Aucune,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Description du paramètre de métadonnées :

ParamètreDescriptionCas d'utilisation
aliasAlias pour le nom du paramètre dans l'URLLe nom du paramètre contient un trait d'union (par ex.item-query), lorsqu'il ne s'agit pas d'un nom de variable Python valide
titleTitre du paramètreAfficher le titre du paramètre dans la documentation
descriptionDescription des paramètresAfficher la description détaillée du paramètre dans la documentation
deprecatedMarqué comme obsolèteLe paramètre peut toujours être utilisé, mais il sera marqué comme « deprecated » dans la documentation.
include_in_schemaIndique s'il doit apparaître dans la documentation de l'APIDéfini commeFalseParamètres pouvant être masqués

Exclure des paramètres d'OpenAPI

Si un paramètre de requête ne doit pas apparaître dans la documentation de l'API :

Exemple

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()


@app.get("/items/")
async def read_items(
    # hidden_query n'apparaîtra pas dans la documentation de l'API, mais il peut toujours être utilisé
    hidden_query: Annotated[str | None, Query(include_in_schema=False)] = Aucune,
):
    if hidden_query:
        return {"hidden_query": hidden_query}
    return {"items": [{"item_id": "Foo"}]}

Résumé

Points clés de la validation des paramètres de requête :

  • UtilisationAnnotated + QueryDéclaration des règles de validation (approche recommandée)
  • Validation de chaîne :min_length、max_length、pattern
  • Pas de valeur par défaut = paramètre obligatoire ; avec valeur par défaut = paramètre facultatif
  • aliasUtilisé pour les noms de paramètres dans les URL qui ne sont pas des noms de variables Python valides.
  • deprecated=TrueMarquage des paramètres obsolètes
  • Utilisationlist[str]Recevoir plusieurs paramètres de requête portant le même nom
autres extensions