Skip to content

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 :

  1. Routes : Tous les décorateurs @app.get, @app.post, etc.
  2. Paramètres : Les paramètres de chemin (ship_id: int) et de requête.
  3. Modèles Pydantic : Vos "plans" (Spaceship, SpaceshipCreate).
  4. 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 et PUT, 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",
)
Maintenant, le titre et la description apparaîtront en haut de votre documentation.

É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
Maintenant, toutes vos opérations CRUD seront soigneusement regroupées sous le titre "Vaisseaux spatiaux".


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

1. FastAPI génère la documentation basée sur...

2. Quelle norme est à la base de l'auto-documentation FastAPI ?

3. À quelle URL la documentation interactive Swagger UI est-elle accessible par défaut ?

4. Le paramètre `tags` dans le décorateur `@app.get` est utilisé pour :

5. ReDoc est...


🚀 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.