Skip to content

Chapitre 6.4 : Documentation de l'API

Temps d'étude : 30 minutes

1. Pourquoi documenter une API ?

Imaginez qu'on vous donne une télécommande d'un vaisseau spatial complexe sans aucune étiquette sur les boutons. Vous les presseriez au hasard, risquant de lancer le siège éjectable au lieu d'allumer la lumière. La documentation d'API, ce sont ces étiquettes et ces instructions.

Une bonne documentation :

  • Économise du temps : Les développeurs n'ont pas à deviner quels sont les points d'API existants, quels paramètres ils acceptent et ce qu'ils retournent.
  • Réduit les erreurs : Une description claire des formats de données et des codes d'erreur aide à éviter une mauvaise utilisation de l'API.
  • Simplifie l'intégration : L'équipe frontend peut travailler en parallèle avec l'équipe backend, en se basant sur la documentation comme sur un contrat.
  • Est votre héritage : Dans six mois, vous vous remercierez vous-même lorsque vous reviendrez sur le projet.

💡 Analogie spatiale :

  • API = Système de contrôle complexe d'une station spatiale.
  • Documentation de l'API = Guide pour les astronautes. Il décrit :
  • Quelle commande (point d'API) envoyer pour ouvrir le sas.
  • Quels paramètres (corps de requête) transmettre pour configurer le système de survie.
  • Quels signaux (réponses de l'API) attendre en retour.

2. Documentation dans FastAPI : La magie automatique

FastAPI rend la documentation incroyablement simple. Il génère automatiquement une documentation interactive basée sur votre code, en utilisant les standards OpenAPI et Swagger UI.

Étape 1 : Ajoutez des métadonnées à votre application

Dans main.py, vous pouvez ajouter des descriptions qui apparaîtront dans la documentation.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel, Field

# ... (code FastAPI)

app = FastAPI(
    title="SpaceAPI",
    description="""
API pour l'exploration de la galaxie. 🚀

Vous pourrez :
* **Consulter les planètes**.
* **Ajouter de nouveaux mondes** (authentification requise).
    """,
    version="1.0.0",
    contact={
        "name": "Ingénieur en chef du centre de contrôle",
        "url": "https://example.com/contact",
        "email": "engineer@example.com",
    },
)

Étape 2 : Décrivez vos modèles et points d'API

Plus vous décrivez en détail les modèles Pydantic et les paramètres des points d'API, meilleure sera la documentation.

# Dans le fichier des modèles Pydantic ou dans main.py

class PlanetBase(BaseModel):
    name: str = Field(..., example="Terre", description="Nom de la planète")
    description: str = Field(..., example="Planète bleue avec une vie diverse", description="Brève description")
    # ...

class Planet(PlanetBase):
    id: int
    is_habitable: bool

    class Config:
        orm_mode = True # ou from_attributes = True dans Pydantic v2

# Dans le fichier des routes
@router.get(
    "/planets",
    response_model=list[Planet],
    summary="Obtenir la liste de toutes les planètes",
    description="Retourne une liste de toutes les planètes connues avec pagination (à l'avenir)."
)
def get_planets():
    # ...

@router.post(
    "/planets",
    # ...
    summary="Créer une nouvelle planète",
    responses={
        401: {"description": "Utilisateur non autorisé"},
        422: {"description": "Erreur de validation des données"}
    }
)
def create_planet(planet: PlanetCreate, ...):
    # ...
  • Field(..., example="..."): Ajoute des exemples à la documentation.
  • summary: Brève description du point d'API.
  • description: Description détaillée.
  • responses: Description des codes de réponse possibles, en dehors du succès.

Étape 3 : Ouvrez la documentation dans le navigateur

Lancez votre serveur FastAPI et ouvrez deux URL magiques :

  1. http://127.0.0.1:8000/docs — ouvrira la documentation interactive Swagger UI. Ici, vous pouvez non seulement lire, mais aussi tester vos points d'API directement depuis le navigateur !
  2. http://127.0.0.1:8000/redoc — ouvrira une vue alternative de la documentation ReDoc. Elle est moins interactive, mais souvent plus lisible.

3. Documentation dans Laravel : Utilisation de paquets tiers

Contrairement à FastAPI, Laravel ne génère pas de documentation "prête à l'emploi". Cependant, il existe d'excellents paquets qui le font en analysant votre code. Le plus populaire est Scribe.

Étape 1 : Installation de Scribe 

composer require --dev "knuckleswtf/scribe"

php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate

Étape 2 : Description des points d'API avec les DocBlocks

Scribe lit les DocBlocks PHP (commentaires de type /** ... */) au-dessus des méthodes de votre contrôleur.

Ouvrez app/Http/Controllers/PlanetController.php :

// app/Http/Controllers/PlanetController.php

/**
 * @group Planètes
 * API pour la gestion des planètes
 */
class PlanetController extends Controller
{
    /**
     * Obtenir la liste des planètes
     *
     * Retourne une liste paginée de toutes les planètes de la galaxie.
     *
     * @unauthenticated
     */
    public function index()
    {
        // ...
    }

    /**
     * Créer une nouvelle planète
     *
     * @authenticated
     *
     * @bodyParam name string required Nom de la planète. Example: Kepler-186f
     * @bodyParam description string required Description de la planète.
     * @bodyParam size_km integer required Diamètre en kilomètres. Example: 14000
     * @bodyParam is_habitable boolean La planète est-elle habitable. Example: true
     *
     * @response 201 {
     *  "id": 4,
     *  "name": "Kepler-186f",
     *  "description": "Première planète de la taille de la Terre confirmée dans la zone habitable d'une autre étoile.",
     *  "size_km": 14000,
     *  "is_habitable": true,
     *  "created_at": "2023-10-27T12:00:00.000000Z",
     *  "updated_at": "2023-10-27T12:00:00.000000Z"
     * }
     */
    public function store(Request $request)
    {
        // ...
    }
    // ... et ainsi de suite pour les autres méthodes
}

Balises clés de Scribe :

  • @group: Regroupe les points d'API.
  • @unauthenticated / @authenticated: Indique si un jeton est requis.
  • @bodyParam: Décrit un paramètre dans le corps de la requête.
  • @response: Exemple de réponse réussie.

Étape 3 : Génération et visualisation de la documentation

Chaque fois après avoir apporté des modifications aux DocBlocks, exécutez la commande :

php artisan scribe:generate
Scribe créera une page HTML statique avec votre documentation. Ouvrez-la à l'adresse : http://your-app-url/docs.

Quiz pour la consolidation

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

2. Quelle URL ouvre Swagger UI dans FastAPI par défaut ?

3. Paquet populaire pour la génération de documentation dans Laravel :

4. Dans Scribe, la balise utilisée pour décrire les paramètres du corps de la requête est :

🚀 Résumé du chapitre :

Vous avez créé une documentation professionnelle, transformant vos API de "boîtes noires" en outils clairs et faciles à utiliser.

  • ✅ Compris l'importance critique de la documentation des API.
  • 🪄 Appris à utiliser la génération automatique de documentation dans FastAPI.
  • ⚙️ Maîtrisé les bases du paquet Scribe pour documenter les API avec Laravel.
  • 🛰️ Constaté qu'une bonne documentation est le meilleur allié de tout développeur.

Vos API fonctionnent et sont sécurisées, et elles sont désormais entièrement prêtes à être utilisées par d'autres membres de l'équipe. Il ne reste qu'une dernière étape, mais la plus importante : la vérification finale de la sécurité.

📌 Vérification :

  • Pour FastAPI : ouvrez /docs dans le navigateur et essayez d'effectuer une requête GET vers la liste des planètes directement depuis l'interface Swagger UI.
  • Pour Laravel : exécutez php artisan scribe:generate et ouvrez /docs. Assurez-vous que les points d'API sont regroupés et que la méthode store a une description des paramètres.