Chapitre 3.5 : Documentation Swagger automatique
Temps d'étude : 30 minutes
1. Documentation API : Le manuel d'utilisation de la station spatiale
Imaginez que vous êtes un nouvel astronaute arrivant à l'ISS. Comment sauriez-vous à quoi sert chaque interrupteur et comment contrôler le bras robotique ? Il vous faudrait un manuel détaillé et à jour.
La documentation API est un manuel similaire pour les développeurs. Elle explique :
- Quels "ports d'amarrage" (endpoints) sont disponibles.
- Quelles "commandes" (méthodes HTTP) peuvent être envoyées.
- Quelle "cargaison" (données) doit être transmise.
- Quelle "télémétrie" (réponses) attendre.
Le problème est que la rédaction manuelle de la documentation est longue, fastidieuse et qu'elle est presque toujours obsolète.
💡 Analogie spatiale :
La documentation manuelle, ce sont des plans papier qui se trouvent dans les archives et ne sont pas mis à jour après la modernisation de la station. La documentation automatique FastAPI est un écran interactif au centre de contrôle des missions, qui se met à jour en temps réel après chaque modification sur la station.
2. La magie de FastAPI : Comment ça marche ?
FastAPI fait tout le "sale boulot" pour vous, en se basant sur votre propre code. Il scanne :
- Routes : Tous les décorateurs
@app.get
,@app.post
, etc. - Paramètres : Les paramètres de chemin (
ship_id: int
) et de requête. - Modèles Pydantic : Vos "plans" (
Spaceship
,SpaceshipCreate
). - Chaînes de documentation (docstrings) : Les descriptions que vous écrivez entre guillemets triples.
Sur la base de ces données, FastAPI génère un schéma selon la norme OpenAPI (anciennement connue sous le nom de Swagger), puis l'affiche via deux belles interfaces.
3. Explorons l'"écran du centre de contrôle des missions" : Swagger UI
Swagger UI est une interface interactive qui permet non seulement de lire la documentation, mais aussi de tester l'API directement depuis le navigateur.
Ouvrez http://127.0.0.1:8000/docs
Vous verrez :
- Liste des endpoints : Regroupés par balises (par défaut, par nom de ressource) et colorés selon les méthodes HTTP.
- Descriptions : Les textes de vos docstrings (
"""..."""
) s'affichent comme descriptions des endpoints. - Paramètres : Indique les paramètres (comme
ship_id
) attendus par l'endpoint, leur type et leur caractère obligatoire. - Corps de la requête (Request Body) : Pour
POST
etPUT
, affiche le schéma JSON généré à partir de votre modèle Pydantic (SpaceshipCreate
). - Réponses (Responses) : Affiche les codes de statut possibles et les schémas de réponse, basés sur
response_model
. - Bouton "Try it out" : Permet de renseigner les paramètres et d'envoyer une requête réelle à votre serveur.
4. Améliorer la documentation : Balises et descriptions
Rendons notre documentation encore plus professionnelle.
Étape 1 : Ajouter des métadonnées dans FastAPI
Lors de la création de l'objet app
, vous pouvez transmettre des informations générales sur votre API.
Modifiez la ligne app = FastAPI()
dans main.py
:
# main.py
app = FastAPI(
title="API de Gestion de Flotte",
description="API pour la gestion d'une flotte de vaisseaux spatiaux.",
version="1.0.0",
)
Étape 2 : Regrouper les endpoints à l'aide de balises Vous pouvez ajouter des balises à chaque endpoint pour les regrouper par signification.
Ajoutez le paramètre tags
aux décorateurs :
# GET /spaceships
@app.get("/spaceships", response_model=List[Spaceship], tags=["Vaisseaux spatiaux"])
# ...
# GET /spaceships/{ship_id}
@app.get("/spaceships/{ship_id}", response_model=Spaceship, tags=["Vaisseaux spatiaux"])
# ...
# POST /spaceships
@app.post("/spaceships", response_model=Spaceship, status_code=201, tags=["Vaisseaux spatiaux"])
# ...
# et ainsi de suite pour PUT et DELETE
5. Vue alternative : ReDoc
FastAPI fournit une autre interface de documentation "prête à l'emploi" — ReDoc. Elle est moins interactive, mais est souvent considérée comme plus lisible et convient parfaitement à la documentation statique.
Ouvrez http://127.0.0.1:8000/redoc
Vous verrez une mise en page à trois colonnes avec navigation, descriptions des endpoints et schémas de données. C'est un excellent moyen de fournir de la documentation à vos "clients" (par exemple, l'équipe frontend).
Quiz de révision
🚀 Résumé du chapitre :
Vous avez découvert l'une des "superpouvoirs" les plus puissants de FastAPI : la création de documentation sans aucun effort.
- 📖 Votre API dispose désormais de deux types de documentation à jour : Swagger UI et ReDoc.
- 🔬 La documentation est interactive et permet de tester l'API à la volée.
- 🏷️ Vous avez appris à l'améliorer à l'aide de métadonnées et de balises.
Le manuel d'utilisation est prêt et toujours à jour ! Dans le dernier chapitre de cette section, nous apprendrons à gérer les "anomalies spatiales" — les erreurs et les données incorrectes.
📌 Vérification :
- Assurez-vous que le titre, la description et les endpoints regroupés par balises s'affichent à l'adresse
http://127.0.0.1:8000/docs
.- Vérifiez que votre modèle
Spaceship
est visible dans la section "Schemas".- Ouvrez
http://127.0.0.1:8000/redoc
et évaluez la vue alternative.⚠️ Si les modifications ne s'affichent pas :
- Assurez-vous d'avoir enregistré le fichier
main.py
.- Vérifiez que le serveur
uvicorn
est lancé avec le drapeau--reload
et qu'il a redémarré avec succès.