Générateur de documentation d'API

Que fait Générateur de documentation d'API ?

Extrait la documentation d'API à partir du code des gestionnaires de routes existants. Lit votre code source, infère les schémas et produit des spécifications OpenAPI, des types TypeScript et des exemples curl exécutables – non pas à partir d'une intention de conception, mais de l'implémentation réelle.

Déclencheurs d'activation

Activer sur : "générer documentation API", "OpenAPI à partir du code", "documenter les endpoints", "référence API", "génération Swagger", "documentation des endpoints", "créer des types API", "exemples curl pour l'API"

PAS pour : Conception d'API à partir de zéro --> api-architect | Rédaction OpenAPI sans code source --> openapi-spec-writer | Tests d'API --> test-automation-expert

Capacités principales

• Extraire les définitions de routes d'Express, Next.js App Router, Next.js Pages API routes, Fastify et Hono
• Inférer les schémas de requête/réponse à partir des types TypeScript, des schémas Zod ou de la validation à l'exécution
• Générer des spécifications OpenAPI 3.0/3.1 avec des paramètres de chemin, des chaînes de requête et des corps de requête précis
• Produire des définitions de types TypeScript correspondant au contrat API réel
• Créer des exemples curl pour chaque endpoint avec des données d'exemple réalistes
• Documenter les exigences d'authentification en traçant les chaînes de middleware
• Identifier la configuration de limite de débit et documenter les limites par endpoint
• Cataloguer les réponses d'erreur en analysant les schémas de throw/return dans les gestionnaires
• Détecter les endpoints non documentés (routes qui existent mais sans JSDoc ni schéma)

Détection du framework

Avant de générer quoi que ce soit, identifiez le framework. La stratégie d'extraction diffère considérablement.

Express / similaire à Express

Signaux : app.get(), router.post(), express.Router()
Source des routes : app._router.stack ou fichiers router explicites
Chaîne middleware : l'ordre de app.use() est important pour la détection d'authentification

Recherchez les modèles d'enregistrement de routes :

• router.get('/users/:id', authenticate, getUser) – middleware avant le gestionnaire signifie authentification requise
• app.use('/api/v1', rateLimiter({ max: 100 }), apiRouter) – limiteur de débit appliqué à un sous-arbre

Next.js App Router

Signaux : fichiers route.ts exportant GET, POST, PUT, DELETE, PATCH
Source des routes : Convention basée sur le système de fichiers dans app/api/
Chaîne middleware : middleware.ts aux limites des répertoires

Les paramètres de chemin proviennent des noms de dossiers : app/api/users/[id]/route.ts --> /api/users/{id}

Routes API Pages Next.js

Signaux : pages/api/**/*.ts avec export par défaut du gestionnaire
Source des routes : Convention basée sur le système de fichiers
Routage par méthode : switch req.method à l'intérieur du gestionnaire

Fastify

Signaux : fastify.get(), fastify.route(), propriété schema sur les options de route
Source des routes : Enregistrement de plugins avec fastify.register()
Schéma : Les routes Fastify ont souvent un schéma JSON déjà – extraire et convertir

Fastify est le framework le plus facile à documenter car les routes déclarent fréquemment leurs propres schémas. Priorisez l'extraction des schema.body, schema.response et schema.querystring existants avant de procéder à l'inférence.

Hono

Signaux : app.get(), app.post(), Hono(), zValidator()
Source des routes : Chaînage de méthodes sur une instance Hono
Validation : basée sur Zod via le middleware zValidator

Hono avec zValidator vous donne les schémas Zod directement. Convertissez Zod --> JSON Schema --> OpenAPI schema.

Processus d'extraction

Étape 1 : Découvrir les routes

Analysez le projet à la recherche d'enregistrement de routes. Ne vous fiez pas à un seul point d'entrée – les frameworks répartissent souvent les routes entre plusieurs fichiers.

# Express : trouver les fichiers router
grep -rl "express.Router\|app.get\|app.post\|router\." src/ --include="*.ts" --include="*.js"

# Next.js App Router : trouver les gestionnaires de routes
find src/app/api -name "route.ts" -o -name "route.js"

# Next.js Pages : trouver les routes API
find src/pages/api -name "*.ts" -o -name "*.js"

# Fastify : trouver les enregistrements de routes
grep -rl "fastify\.\(get\|post\|put\|delete\|route\)" src/ --include="*.ts"

# Hono : trouver les définitions de routes
grep -rl "app\.\(get\|post\|put\|delete\|patch\)" src/ --include="*.ts"

Étape 2 : Extraire les schémas

Pour chaque route, identifiez les formes de la requête et de la réponse.

Ordre de priorité pour les sources de schémas :

1. Schémas de validation explicites (Zod/Joi/Yup) (confiance la plus élevée)
2. Annotations de type TypeScript sur la requête/réponse
3. Déclarations de schémas JSON (Fastify)
4. Annotations JSDoc @param / @returns
5. Inférence à l'exécution à partir de la construction de la réponse (confiance la plus basse – marquer comme approximatif)

Lors de l'utilisation de l'inférence à l'exécution (option 5), marquez toujours le schéma avec x-inferred: true dans la sortie OpenAPI afin que les consommateurs sachent qu'il peut être incomplet.

Étape 3 : Tracer l'authentification

Parcourez la chaîne middleware pour chaque route afin de déterminer les exigences d'authentification :

• Pas de middleware d'authentification : Marquer comme security: [] (public)
• Middleware jeton Bearer : Marquer comme security: [{ bearerAuth: [] }]
• Middleware clé API : Marquer comme security: [{ apiKeyAuth: [] }]
• Authentification session/cookie : Marquer comme security: [{ cookieAuth: [] }]
• Options d'authentification multiples : Lister toutes comme alternatives dans le tableau security

Étape 4 : Cataloguer les erreurs

Lisez chaque gestionnaire et listez chaque réponse d'erreur :

• res.status(400).json(...) ou throw new BadRequestError(...) --> schéma de réponse 400
• res.status(401) --> 401 (inclure si middleware d'auth présent même sans throw explicite)
• res.status(404) --> 404
• res.status(409) --> 409 (conflit, courant dans les opérations de création)
• res.status(422) --> 422 (échec de validation)
• res.status(429) --> 429 (limité, inclure si un middleware de limiteur de débit est détecté)
• res.status(500) --> 500 (toujours inclure comme possibilité)

Étape 5 : Générer les sorties

Produisez trois artefacts :

1. Spécification OpenAPI (YAML, pas JSON – plus lisible, plus facile à diff)
2. Types TypeScript (fichier .d.ts autonome avec tous les types de requête/réponse)
3. Exemples curl (un par endpoint, avec en-têtes et charges utiles d'exemple)

Points de décision

Lorsque la base de code n'a PAS de schémas de validation

Si les gestionnaires acceptent req.body brut sans validation Zod/Joi, vous devez inférer les types à partir de l'utilisation. Recherchez :

• Modèles d'accès aux propriétés : req.body.name, req.body.email --> { name: string, email: string }
• Destructuration : const { name, email } = req.body --> même inférence
• Appels d'insertion en base de données : db.users.create({ name: body.name }) --> croiser le schéma DB si disponible

Marquez l'ensemble de la spécification avec un avertissement : x-schemas-inferred: true au niveau de l'info.

Lorsque les routes utilisent des segments de chemin dynamiques

• Express : :id --> OpenAPI {id}
• Next.js : [id] --> OpenAPI {id}
• Next.js catch-all : [...slug] --> OpenAPI {slug} avec note sur le comportement du tableau
• Fastify : :id --> OpenAPI {id}
• Hono : :id --> OpenAPI {id}

Lorsque la forme de la réponse varie selon le code de statut

Documentez chaque code de statut avec son propre schéma. Ne fusionnez pas 200 et 201 en un seul schéma s'ils diffèrent. Modèle courant :

responses:
  '200':
    description: Utilisateur trouvé
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  '404':
    description: Utilisateur non trouvé
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'

Lorsque les limites de débit diffèrent par endpoint

Documentez les limites de débit à l'aide d'extensions OpenAPI :

x-rate-limit:
  requests: 100
  window: 60s
  scope: per-api-key

Si le limiteur de débit est global (appliqué une fois au niveau de l'application), documentez-le dans la section info de niveau supérieur. S'il est par route, documentez-le sur chaque opération.

Génération de types TypeScript

Générez des types qui correspondent exactement à la spécification OpenAPI. Utilisez des types "branded" pour les ID lorsque la base de code les utilise.

// Généré à partir de la spécification OpenAPI – ne pas modifier manuellement

export interface CreateUserRequest {
  name: string;
  email: string;
  role?: 'admin' | 'member' | 'viewer';
}

export interface CreateUserResponse {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'member' | 'viewer';
  createdAt: string; // ISO 8601
}

export interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details?: Array<{
      field: string;
      issue: string;
    }>;
  };
}

export interface PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    perPage: number;
    total: number;
    hasMore: boolean;
  };
}

Génération d'exemples curl

Générez une commande curl par endpoint. Utilisez des données réalistes mais visiblement fictives.

# GET /api/users/:id – Récupérer un seul utilisateur
curl -X GET https://api.example.com/api/users/usr_abc123 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Accept: application/json"

# POST /api/users – Créer un nouvel utilisateur
curl -X POST https://api.example.com/api/users \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "[email protected]",
    "role": "member"
  }'

# GET /api/users – Lister les utilisateurs avec pagination
curl -X GET "https://api.example.com/api/users?page=1&perPage=20&role=admin" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Accept: application/json"

Règles pour les exemples curl :

• Incluez toujours l'URL complète (utilisez https://api.example.com comme base)
• Incluez tous les en-têtes requis
• Utilisez -d avec du JSON formaté pour les corps de requête
• Mettez entre guillemets les URL qui contiennent des paramètres de requête
• Affichez la méthode HTTP explicitement, même pour GET
• Utilisez sk_test_... pour les jetons d'authentification (visiblement faux)
• Utilisez des valeurs de champ réalistes, pas "string" ou "test"

Anti-modèles

1. Documenter des API aspirantes

Symptôme : La spécification décrit des endpoints qui n'existent pas encore dans le code Correction : Documentez uniquement ce que le code implémente réellement. Si un endpoint planifié se trouve dans des commentaires ou un fichier de spécifications mais pas dans les gestionnaires, excluez-le.

2. Ignorer les effets de bord du middleware

Symptôme : La documentation indique qu'un endpoint est public alors qu'il nécessite en réalité une authentification via un middleware parent Correction : Tracez la chaîne middleware complète de la racine de l'application au gestionnaire. Un router.use(auth) au-dessus de la définition de route signifie que toutes les routes en dessous nécessitent une authentification.

3. Supposer la forme du corps de la requête

Symptôme : Documenter req.body comme any ou object car il n'y a pas de validation Correction : Inférer à partir de l'utilisation (accès aux propriétés, destructuration, appels à la base de données). Marquer comme x-inferred: true. Recommander d'ajouter une validation Zod.

4. Documentation d'erreur plate

Symptôme : Chaque endpoint liste le même "400 Bad Request" générique sans détails Correction : Lisez les chemins d'erreur de chaque gestionnaire. Documentez les codes d'erreur et les messages spécifiques renvoyés. Différents échecs de validation doivent montrer des exemples de réponses différents.

5. Documentation générée obsolète

Symptôme : La spécification a été générée une fois et jamais mise à jour au fur et à mesure que le code changeait Correction : Générez dans un chemin bien connu (docs/openapi.yaml). Ajoutez une vérification CI qui régénère et diffère avec la spécification validée. S'ils divergent, échouez la build.

6. Documentation de pagination manquante

Symptôme : Endpoints de liste documentés sans schémas de paramètres de requête pour la pagination Correction : Si le gestionnaire prend en charge page, limit, cursor, offset ou des paramètres similaires, documentez-les avec les valeurs par défaut et maximales.

7. Téléchargements de fichiers non documentés

Symptôme : Endpoints multipart/form-data documentés en JSON Correction : Détectez multer, formidable, busboy ou la gestion des fichiers native du framework. Utilisez le type de contenu multipart/form-data avec un schéma binaire approprié.

Liste de contrôle qualité

[ ] Chaque gestionnaire de route dans la base de code a une opération OpenAPI correspondante
[ ] Les paramètres de chemin correspondent entre le code et la spécification (pas de divergence :id vs {userId})
[ ] Les schémas de corps de requête couvrent tous les champs obligatoires et facultatifs
[ ] Les schémas de réponse correspondent à la structure JSON réelle (vérifié en lisant le return du gestionnaire)
[ ] Les exigences d'authentification correspondent à l'analyse de la chaîne middleware
[ ] Les informations de limite de débit sont documentées là où un middleware de limiteur de débit existe
[ ] Les réponses d'erreur sont cataloguées à partir des instructions throw/return réelles dans les gestionnaires
[ ] Les exemples curl s'exécutent avec succès contre une instance en cours d'exécution
[ ] Les types TypeScript se compilent sans erreur
[ ] Aucun schéma x-inferred laissé non documenté (chacun signalé a un TODO pour une validation appropriée)
[ ] Les paramètres de pagination sont documentés avec les valeurs par défaut et maximales
[ ] Les endpoints de téléchargement de fichiers utilisent le type de contenu multipart/form-data
[ ] La spécification OpenAPI est validée avec spectral ou swagger-cli lint
[ ] La spécification générée est validée dans un chemin connu pour le diff CI

Artéfacts de sortie

1. docs/openapi.yaml – Spécification OpenAPI 3.0/3.1 complète
2. docs/api-types.d.ts – Définitions de types TypeScript pour toutes les formes de requête/réponse
3. docs/api-examples.sh – Exemples curl exécutables pour chaque endpoint
4. docs/api-coverage.md – Rapport listant les routes documentées vs non documentées

Validation

# Linter la spécification OpenAPI générée
npx @stoplight/spectral-cli lint docs/openapi.yaml

# Valider la structure de la spécification
npx swagger-cli validate docs/openapi.yaml

# Générer un client TypeScript pour vérifier que les types se compilent
npx openapi-typescript docs/openapi.yaml -o /tmp/api-check.d.ts
tsc --noEmit /tmp/api-check.d.ts

# Différer par rapport à la dernière spécification validée (vérification CI)
diff <(cat docs/openapi.yaml) <(npx tsx scripts/generate-api-docs.ts --stdout) && echo "La spécification est à jour" || echo "La spécification est obsolète"

---

Couvre : Génération OpenAPI | Extraction de types TypeScript | Création d'exemples curl | Documentation d'authentification | Documentation des limites de débit | Catalogage des codes d'erreur

Utiliser avec : api-architect (conception d'abord, documenter après) | openapi-spec-writer (rédaction manuelle) | test-automation-expert (test de contrat contre la spécification générée)