DEV Community

Cover image for Comment créer de la documentation API avec un agent IA via Apidog CLI
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment créer de la documentation API avec un agent IA via Apidog CLI

La documentation API est essentielle, mais elle prend souvent du retard : un endpoint est livré, la référence n’est pas mise à jour, et le guide de démarrage décrit encore un ancien flux d’authentification. Ce travail est répétitif, facile à reporter et pourtant nécessaire. C’est précisément le type de tâche qu’un agent IA peut automatiser efficacement lorsqu’il peut exécuter des commandes shell.

Essayez Apidog dès aujourd’hui

Avec la CLI Apidog, un agent peut créer des endpoints, générer des schémas, rédiger des guides Markdown et publier un site de documentation depuis une requête en langage clair. Chaque opération est scriptable et renvoie du JSON structuré, que l’agent peut exploiter pour choisir son étape suivante.

Pourquoi utiliser la CLI plutôt qu’une interface graphique ou un serveur MCP ?

Ces approches répondent à des besoins différents :

Approche Direction Opérateur Différentiel révisable ?
Interface graphique Édition manuelle dans un navigateur Une personne Non
Serveur MCP Lit une spécification puis écrit du code Un agent dans l’éditeur Dans le dépôt de code, pas dans la documentation
CLI Crée et publie la documentation Un agent dans un terminal Oui, via les commandes exécutées

Un serveur MCP est utile lorsqu’un agent doit lire votre définition d’API pour générer du code client. Le flux de documentation MCP de Cursor en est un bon exemple.

Ici, l’objectif est différent : l’agent doit produire la documentation elle-même.

La CLI est adaptée à ce flux pour trois raisons :

  1. Déterministe : une même commande produit le même résultat.
  2. Scriptable : le flux peut être intégré dans une CI.
  3. Guidée par JSON : chaque réponse peut inclure agentHints.nextSteps, afin que l’agent suive les prochaines actions suggérées plutôt que de les deviner.

Configurer l’environnement de l’agent

Installez la CLI, puis authentifiez-vous une fois :

npm install -g apidog-cli
apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Consultez le guide d’installation pour les prérequis Node.js et PATH, ainsi que le guide d’authentification pour les jetons et secrets CI.

Configuration de la CLI Apidog

Récupérez le jeton dans l’application Apidog :

Avatar utilisateur → Paramètres du compte → Jeton d’accès API

Après connexion, le jeton est stocké localement. L’agent n’a donc pas besoin de le fournir à chaque commande.

Création d’un jeton d’accès API

Chaque commande d’écriture nécessite un ID de projet. Vous pouvez le récupérer dans :

Paramètres du projet → Paramètres de base

Ou via la CLI :

apidog project list
Enter fullscreen mode Exit fullscreen mode

Tout agent capable d’exécuter des commandes shell peut utiliser ce flux : Claude Code, Cursor, Codex ou un autre agent de développement.

Utilisation de la CLI par un agent

Configuration d’un agent avec Apidog

Le rituel d’écriture à imposer à l’agent

Ne laissez pas l’agent inventer une charge utile JSON à partir de sa mémoire. Les noms de champs incorrects sont une cause fréquente d’échec.

Pour chaque commande qui crée ou met à jour une ressource, utilisez toujours cette séquence :

# 1. Lire le schéma attendu par la CLI
apidog cli-schema get doc-create

# 2. Générer le fichier JSON à partir de ce schéma

# 3. Valider le fichier localement
apidog cli-schema validate doc-create --file ./doc.json

# 4. Exécuter seulement ensuite la commande d’écriture
apidog doc create --project <projectId> --file ./doc.json
Enter fullscreen mode Exit fullscreen mode

Ajoutez ces règles dans l’invite système de votre agent, dans CLAUDE.md ou dans .cursorrules :

Règles Apidog CLI :
- Ne jamais écrire manuellement une charge utile JSON. Exécutez d'abord `apidog cli-schema get <commande>` et construisez le fichier à partir de ce schéma.
- Validez chaque fichier avec `apidog cli-schema validate <commande> --file <fichier>` avant toute création ou mise à jour.
- Toujours passer --project <projectId> sur les commandes d'écriture.
- Lisez le champ `agentHints.nextSteps` dans chaque réponse JSON pour choisir la commande suivante.
- Si une écriture est bloquée par des autorisations, arrêtez-vous et demandez à l'humain ; ne contournez pas les permissions.
Enter fullscreen mode Exit fullscreen mode

Cette boucle évite qu’un champ inventé par le modèle devienne un échec lors de l’exécution ou de la CI.

Étape 1 : créer la référence API depuis les endpoints et les schémas

Dans Apidog, la référence API est générée à partir des endpoints et des schémas de données du projet.

Supposons que vous demandiez à l’agent :

« Ajoutez un endpoint POST /refunds qui prend un ID de commande et un montant, puis documentez les réponses de succès et d’erreur de validation. »

L’agent doit commencer par créer un modèle de données réutilisable.

1. Créer le schéma de remboursement

Demandez à la CLI le schéma de création :

apidog cli-schema get schema-create
Enter fullscreen mode Exit fullscreen mode

Créez ensuite refund-schema.json :

{
  "name": "Remboursement",
  "description": "Un remboursement émis pour une commande",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Validez et créez la ressource :

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
Enter fullscreen mode Exit fullscreen mode

Conservez l’ID du schéma créé : il sera utilisé par l’endpoint.

2. Créer l’endpoint POST /refunds

Le schéma endpoint-create requiert notamment method et path.

Créez refunds-endpoint.json :

{
  "name": "Créer un remboursement",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": {
      "$ref": "#/definitions/<refundSchemaId>"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Puis validez et créez l’endpoint :

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json
Enter fullscreen mode Exit fullscreen mode

La référence de /refunds est alors générée depuis la définition que l’équipe maintient dans le projet. Il n’y a pas d’étape distincte d’export pour produire cette référence : le schéma est la source de vérité.

Étape 2 : rédiger les guides Markdown

Une référence générée depuis des schémas ne suffit pas toujours. Les développeurs ont aussi besoin de guides de démarrage, de procédures d’authentification, de notes de migration ou d’exemples d’intégration.

Dans Apidog, ces contenus vivent dans l’arborescence documentaire du projet sous forme de documents Markdown gérés avec les commandes doc.

Le schéma doc-create requiert un name. Le contenu Markdown est transmis dans content, tandis que folderId détermine l’emplacement dans l’arborescence. La valeur 0 correspond à la racine.

Créez quickstart.json :

{
  "name": "Démarrage rapide : Votre premier remboursement",
  "content": "# Démarrage rapide\n\nCe guide vous emmène de la clé API à votre premier remboursement en cinq minutes...",
  "folderId": 0
}
Enter fullscreen mode Exit fullscreen mode

Avant la création, inspectez éventuellement les documents existants :

apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

Validez puis créez le guide :

apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json
Enter fullscreen mode Exit fullscreen mode

Vous pouvez maintenant demander à l’agent :

« Rédige un guide de démarrage rapide qui accompagne un nouveau développeur de la clé API à son premier remboursement. »

L’agent peut produire le Markdown, construire le JSON conforme au schéma, le valider et créer le document sans ouvrir de navigateur ni copier-coller du contenu.

Étape 3 : publier le site de documentation

Apidog distingue trois types de ressources :

  • doc : un document Markdown dans l’arborescence du projet.
  • docs-site : un site de documentation hébergé et public.
  • shared-doc : un lien partageable, destiné par exemple à un partenaire.

Pour créer ou gérer un site de documentation :

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

Utilisez :

  • docs-site pour publier un site de documentation ;
  • shared-doc pour générer un lien de partage ;
  • doc pour créer ou modifier une page Markdown dans le projet.

Puisque la publication est également une commande, elle peut être exécutée automatiquement après une mise à jour de documentation dans la boucle de l’agent ou dans votre CI.

Étape 4 : exporter une copie portable

Vous pouvez également exporter la documentation au format HTML, Markdown ou OpenAPI :

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Si votre projet contient plusieurs services, utilisez l’aide intégrée pour filtrer l’export :

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Les options --scope, --api-ids et --folder-ids permettent de limiter la sortie à une partie précise du projet.

Exemple complet : documenter un service de paiement

Requête adressée à l’agent :

« Nous venons d’ajouter un service de paiement avec POST /refunds et GET /refunds/{id}. Documentez les deux, rédigez un bref guide expliquant les clés d’idempotence, et publiez le tout sur notre site de documentation. »

L’agent suit alors le flux suivant :

# Créer le modèle de données partagé
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Créer les deux endpoints
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Créer un guide Markdown sur l'idempotence
apidog doc create --project $PID --file ./idempotency-guide.json

# Publier le site
apidog docs-site create --project $PID --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

Le rôle humain devient alors simple :

  1. formuler l’intention ;
  2. examiner les changements produits ;
  3. valider le résultat.

Intégrer le flux dans une CI

Chaque étape étant une commande, vous pouvez exporter ou vérifier la documentation à chaque push.

Exemple minimal dans une CI :

- name: Régénérer la documentation API
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

Pour un flux d’agent plus complet, consultez :

Le principe reste identique : décrivez l’intention, laissez l’agent traduire cette intention en commandes CLI validées, puis révisez le résultat.

Gérer les permissions

Les écritures réalisées par un agent peuvent être contrôlées au niveau du projet.

Si une commande create est bloquée, les External AI Edit Permissions peuvent être désactivées pour la branche concernée.

Deux options sont possibles :

  1. Activer l’édition directe dans :

Paramètres du projet → Paramètres des fonctionnalités → Paramètres des fonctionnalités IA

Cette option est disponible dans le client Apidog 2.8.32+.

  1. Faire travailler l’agent sur une branche IA isolée, puis ouvrir une demande de fusion.

Le guide sur la mise à jour d’une spécification API par un agent détaille ce flux de branche IA. Le même principe s’applique à la création de documentation dans une branche protégée.

Pièges courants

L’agent construit le JSON à la main

C’est la principale source d’échec.

Appliquez systématiquement :

cli-schema get → cli-schema validate → create
Enter fullscreen mode Exit fullscreen mode

L’agent doit partir du schéma réel fourni par la CLI, et non d’une structure supposée.

L’ID de projet est absent

Les commandes doc, docs-site et export nécessitent --project.

Utilisez l’ID du projet, pas son nom lisible.

apidog project list
Enter fullscreen mode Exit fullscreen mode

Confusion entre doc, docs-site et shared-doc

Ces commandes ne ciblent pas la même ressource :

Commande Ressource
doc Une page Markdown dans l’arborescence
docs-site Un site de documentation hébergé
shared-doc Un lien de partage

Demandez à l’agent de confirmer la cible avant toute écriture.

Jeton absent dans la CI

apidog login stocke le jeton sur la machine qui exécute la commande. Chaque nouveau runner CI doit donc s’authentifier dans le même job :

apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Conservez toujours le jeton dans un secret CI.

Référence $ref invalide

Un endpoint qui contient :

{
  "$ref": "#/definitions/<schemaId>"
}
Enter fullscreen mode Exit fullscreen mode

ne fonctionnera que si le schéma existe déjà.

Créez donc les schémas avant les endpoints qui les référencent.

FAQ

Quels agents IA peuvent utiliser la CLI Apidog ?

Tout agent capable d’exécuter des commandes shell : Claude Code, Cursor, Codex et les agents de développement similaires.

Ai-je besoin d’un plan payant ?

Non. Apidog n’est pas open source, mais le niveau gratuit et apidog-cli couvrent le flux de création et de publication décrit ici.

L’agent peut-il écraser un document existant ?

create ajoute de nouvelles ressources. Les modifications utilisent update, qui demande ses propres garde-fous. Consultez le guide de mise à jour de spécification API pour ce cas.

Quelle différence avec un générateur de documentation IA générique ?

Un générateur générique produit surtout du texte depuis votre code. Ici, l’agent produit de la documentation structurée dans votre plateforme API : schémas, endpoints, guides et site publié, tous reliés à une source de vérité vivante.

Conclusion

Un agent qui peut exécuter la CLI Apidog peut automatiser la partie de la documentation qui est habituellement reportée :

  • créer les endpoints ;
  • définir les schémas ;
  • rédiger les guides Markdown ;
  • publier le site ;
  • exporter une copie portable si nécessaire.

La règle essentielle est simple :

Obtenir le schéma → valider le JSON → exécuter la commande
Enter fullscreen mode Exit fullscreen mode

Donnez cette boucle à votre agent, fournissez-lui les règles d’écriture et un ID de projet, puis concentrez-vous sur la révision du résultat plutôt que sur la mise à jour manuelle de la documentation.

Téléchargez Apidog pour utiliser la CLI, ou consultez le guide complet de la CLI Apidog.

Top comments (0)