Configurer les chemins d'accès¶
🌐 Traduction par IA et humains
Cette traduction a été réalisée par une IA guidée par des humains. 🤝
Elle peut contenir des erreurs d'interprétation du sens original, ou paraître peu naturelle, etc. 🤖
Vous pouvez améliorer cette traduction en nous aidant à mieux guider le LLM d'IA.
Vous pouvez passer plusieurs paramètres à votre décorateur de chemin d'accès pour le configurer.
Alertes
Notez que ces paramètres sont passés directement au décorateur de chemin d'accès, et non à votre fonction de chemin d'accès.
Définir le code d'état de la réponse¶
Vous pouvez définir le status_code (HTTP) à utiliser dans la réponse de votre chemin d'accès.
Vous pouvez passer directement le code int, comme 404.
Mais si vous ne vous souvenez pas à quoi correspond chaque code numérique, vous pouvez utiliser les constantes abrégées dans status :
from fastapi import FastAPI, status
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item) -> Item:
return item
Ce code d'état sera utilisé dans la réponse et ajouté au schéma OpenAPI.
Détails techniques
Vous pouvez également utiliser from starlette import status.
FastAPI fournit le même starlette.status sous le nom fastapi.status pour votre commodité, en tant que développeur. Mais cela provient directement de Starlette.
Ajouter des tags¶
Vous pouvez ajouter des tags à votre chemin d'accès, en passant le paramètre tags avec une list de str (généralement un seul str) :
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", tags=["items"])
async def create_item(item: Item) -> Item:
return item
@app.get("/items/", tags=["items"])
async def read_items():
return [{"name": "Foo", "price": 42}]
@app.get("/users/", tags=["users"])
async def read_users():
return [{"username": "johndoe"}]
Ils seront ajoutés au schéma OpenAPI et utilisés par les interfaces de documentation automatiques :
Utiliser des tags avec Enum¶
Si vous avez une grande application, vous pourriez finir par accumuler plusieurs tags, et vous voudrez vous assurer d'utiliser toujours le même tag pour les chemins d'accès associés.
Dans ces cas, il peut être judicieux de stocker les tags dans un Enum.
FastAPI le prend en charge de la même manière qu'avec des chaînes simples :
from enum import Enum
from fastapi import FastAPI
app = FastAPI()
class Tags(Enum):
items = "items"
users = "users"
@app.get("/items/", tags=[Tags.items])
async def get_items():
return ["Portal gun", "Plumbus"]
@app.get("/users/", tags=[Tags.users])
async def read_users():
return ["Rick", "Morty"]
Ajouter un résumé et une description¶
Vous pouvez ajouter un summary et une description :
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post(
"/items/",
summary="Create an item",
description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item) -> Item:
return item
Utiliser la description depuis la docstring¶
Comme les descriptions ont tendance à être longues et à couvrir plusieurs lignes, vous pouvez déclarer la description du chemin d'accès dans la docstring de la fonction et FastAPI la lira à partir de là.
Vous pouvez écrire Markdown dans la docstring, il sera interprété et affiché correctement (en tenant compte de l'indentation de la docstring).
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", summary="Create an item")
async def create_item(item: Item) -> Item:
"""
Create an item with all the information:
- **name**: each item must have a name
- **description**: a long description
- **price**: required
- **tax**: if the item doesn't have tax, you can omit this
- **tags**: a set of unique tag strings for this item
"""
return item
Elle sera utilisée dans les documents interactifs :
Définir la description de la réponse¶
Vous pouvez spécifier la description de la réponse avec le paramètre response_description :
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post(
"/items/",
summary="Create an item",
response_description="The created item",
)
async def create_item(item: Item) -> Item:
"""
Create an item with all the information:
- **name**: each item must have a name
- **description**: a long description
- **price**: required
- **tax**: if the item doesn't have tax, you can omit this
- **tags**: a set of unique tag strings for this item
"""
return item
Info
Notez que response_description se réfère spécifiquement à la réponse, tandis que description se réfère au chemin d'accès en général.
Vérifications
OpenAPI spécifie que chaque chemin d'accès requiert une description de réponse.
Donc, si vous n'en fournissez pas, FastAPI en générera automatiquement une « Réponse réussie ».
Déprécier un chemin d'accès¶
Si vous devez marquer un chemin d'accès comme déprécié, sans pour autant le supprimer, passez le paramètre deprecated :
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", tags=["items"])
async def read_items():
return [{"name": "Foo", "price": 42}]
@app.get("/users/", tags=["users"])
async def read_users():
return [{"username": "johndoe"}]
@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
return [{"item_id": "Foo"}]
Il sera clairement marqué comme déprécié dans les documents interactifs :
Voyez à quoi ressemblent les chemins d'accès dépréciés et non dépréciés :
Récapitulatif¶
Vous pouvez facilement configurer et ajouter des métadonnées à vos chemins d'accès en passant des paramètres aux décorateurs de chemin d'accès.