Que fait Générateur de documentation API ?
Cette compétence génère automatiquement la documentation OpenAPI 3.0 (Swagger) à partir des fichiers de routes API de votre codebase.
Quand utiliser cette compétence
- L'utilisateur demande de générer une documentation API
- Vous travaillez avec des endpoints API REST
- Vous devez créer ou mettre à jour des spécifications OpenAPI/Swagger
- Vous mettez en place une documentation API pour Express, FastAPI, Flask, NestJS ou des frameworks similaires
Instructions
1. Découvrir les routes API
Recherchez dans le codebase les définitions de routes API :
- Express/Node.js : Recherchez
app.get(),app.post(),router.get(), etc. - FastAPI/Python : Recherchez
@app.get(),@router.post(), décorateurs - Flask : Recherchez les décorateurs
@app.route() - NestJS : Recherchez les décorateurs
@Get(),@Post(),@Controller() - Rails : Recherchez les routes dans
config/routes.rb
Utilisez Glob pour trouver les fichiers de routes (ex : **/*routes*.{js,ts,py}, **/controllers/**/*.{js,ts})
2. Analyser les modèles de route
Pour chaque route découverte, extrayez :
- Méthode HTTP : GET, POST, PUT, PATCH, DELETE
- Chemin : L'URL de l'endpoint (ex :
/api/users/:id) - Paramètres : Paramètres de chemin, paramètres de requête, corps de la requête
- Réponse : Structure de réponse attendue
- Authentification : Si l'authentification est requise
- Description : Commentaires ou docstrings près de la route
3. Générer la spécification OpenAPI
Créez ou mettez à jour un fichier de spécification OpenAPI 3.0 (généralement openapi.yaml ou swagger.json) :
- Commencez avec le modèle de
templates/openapi-3.0.yaml - Mappez chaque route à un objet de chemin OpenAPI
- Définissez les schémas de requête/réponse en utilisant JSON Schema
- Incluez les définitions de paramètres (chemin, requête, corps)
- Ajoutez les schémas d'authentification si détectés (Bearer, API Key, OAuth2)
- Regroupez les endpoints par balises (ex : "Utilisateurs", "Produits", "Authentification")
4. Valider l'exhaustivité
Vérifiez que la documentation générée inclut :
- Tous les endpoints découverts
- Des méthodes HTTP et chemins précis
- Des exemples de requête/réponse si possible
- Des réponses d'erreur (400, 401, 404, 500, etc.)
- Les exigences de sécurité
5. Emplacement de sortie
- Enregistrez sous
openapi.yamlà la racine du projet, ou - Placez dans le répertoire
docs/ouapi/s'ils existent - Demandez à l'utilisateur l'emplacement préféré en cas de doute
Notes spécifiques aux frameworks
Express/Node.js
- Vérifiez les middleware de route qui pourraient affecter l'authentification/validation
- Recherchez les validateurs de requête (Joi, express-validator, etc.)
- Extrayez les commentaires JSDoc pour les descriptions d'endpoints
FastAPI
- FastAPI génère automatiquement des docs OpenAPI, mais cette compétence peut les améliorer
- Extrayez les modèles Pydantic pour les schémas de requête/réponse
- Vérifiez les paramètres
response_modeletstatus_code
NestJS
- Recherchez les DTO (Data Transfer Objects) pour les schémas
- Vérifiez les décorateurs Swagger (
@ApiOperation,@ApiResponse) - Extrayez les métadonnées des décorateurs de contrôleur et de méthode
Bonnes pratiques
- Utilisez les schémas existants : Si le codebase contient des interfaces TypeScript, des modèles Pydantic ou similaires, utilisez-les pour des schémas précis
- Incluez des exemples : Ajoutez des exemples de requête/réponse à partir des tests si disponibles
- Regroupez logiquement : Organisez les endpoints par ressource ou domaine fonctionnel à l'aide de balises
- Versionnez correctement : Utilisez la version de l'API du codebase (ex : "1.0.0")
- Ajoutez des descriptions : Utilisez les commentaires de code/docstrings pour les descriptions d'endpoints
Fichiers associés
templates/openapi-3.0.yaml: Modèle OpenAPI de baseexamples.md: Exemples spécifiques aux frameworks