Aller au contenu principal

Maintenance de la Documentation API

Ce guide explique comment mettre à jour la documentation lorsque l'API StageConnect évolue.

Flux de Mise à Jour​

Lorsque vous modifiez le code du backend (FastAPI), suivez ces étapes pour synchroniser la documentation :

1. Régénérer la spécification OpenAPI​

Le fichier openapi-stageconnect.json doit être mis à jour à partir du code source de l'application. Depuis la racine du projet, lancez :

cd backend
./venv/bin/python3 -c "
import json
from app.main import app
print(json.dumps(app.openapi()))
" > ../stageconnect-docs/static/openapi-stageconnect.json

2. Régénérer les fichiers MDX de Docusaurus​

Le plugin OpenAPI de Docusaurus transforme le JSON en pages de documentation. Depuis la racine du projet docs :

cd stageconnect-docs
npm run docusaurus gen-api-docs all

3. Nettoyer les anciens fichiers (Optionnel)​

Si vous avez supprimé des endpoints, il est conseillé de vider le dossier docs/api-reference avant de lancer la génération pour éviter les fichiers fantômes :

rm -rf docs/api-reference/*
npm run docusaurus gen-api-docs all

4. Vérifier et Build​

Vérifiez le rendu en local :

npm run start

Puis build pour la prod :

npm run build

Bonnes Pratiques​

  • OperationId : FastAPI génère des OperationId automatiquement, mais vous pouvez les personnaliser avec l'argument operation_id dans @router.get().
  • Tags : Utilisez les tags dans les routeurs pour regrouper les endpoints dans la barre latérale.
  • Schemas : Utilisez des types Literal avec des valeurs par défaut pour les champs discriminants (comme user_type) afin d'alléger la documentation pour les utilisateurs finaux.