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

La documentation API est la tâche que tout le monde s'accorde à dire importante et que personne ne veut prendre en charge. Un nouveau point de terminaison est livré, la référence prend une semaine de retard, et le guide de démarrage décrit un flux d'authentification que vous avez remplacé il y a deux sprints. Le travail est réel, mais il est répétitif et facile à reporter.

Cette combinaison (importante, répétitive, reportable) est exactement ce à quoi un agent IA excelle. Si votre agent peut exécuter une commande de terminal, il peut créer des points de terminaison, rédiger les guides explicatifs les concernant et publier un site de documentation, le tout à partir d'une requête en langage clair. Le CLI Apidog est ce qui rend cela possible : chaque action de documentation est une commande scriptable avec une sortie JSON structurée qu'un agent peut lire et sur laquelle il peut agir.

bouton

Pourquoi la CLI, et non l'interface graphique ou un serveur MCP

Il existe trois façons pour un agent de toucher votre documentation API, et elles résolvent différents problèmes. Bien comprendre cette distinction fait la différence entre lutter contre vos outils et utiliser celui qui est fait pour le travail.

Approche	Direction	Qui l'opère	Différentiel révisable ?
Interface graphique	Édition humaine dans un navigateur	Une personne, en cliquant	Non
Serveur MCP	Lit votre spécification → écrit du code	Un agent, dans votre éditeur	Dans votre dépôt de code, pas la documentation
CLI	Écrit la documentation elle-même	Un agent, dans un terminal	Oui, chaque commande est journalisée

Un serveur MCP est excellent lorsque vous souhaitez qu'un agent lise votre définition d'API et génère du code client en fonction de celle-ci. Le flux de documentation via MCP de Cursor en est un exemple canonique. Mais c'est l'inverse de ce que nous voulons ici. Nous voulons que l'agent produise la documentation : créer des points de terminaison, rédiger des guides Markdown et publier un site.

Pour cela, la CLI l'emporte sur trois points. Elle est déterministe : la même commande produit le même résultat. Elle est scriptable : tout le flux peut être intégré à l'intégration continue (CI). Et elle renvoie du JSON à chaque appel, incluant un champ agentHints.nextSteps qui indique à l'agent ce qu'il peut faire ensuite. Ce dernier point est plus important qu'il n'y paraît : cela signifie que l'agent ne devine pas la suite, il suit les propres suggestions de la CLI.

Configurer l'environnement de l'agent

Installez la CLI et authentifiez-vous une seule fois. Notre guide d'installation couvre les versions de Node et le PATH ; le guide d'authentification couvre les jetons et les secrets CI.

npm install -g apidog-cli
apidog login --with-token <TOKEN>

Récupérez le jeton depuis l'application Apidog sous l'avatar de l'utilisateur → Paramètres du compte → Jeton d'accès API. Il est stocké localement après la connexion, de sorte que l'agent ne le transmet pas à chaque appel.

Chaque écriture s'effectue sur un ID de projet, que vous trouverez dans Paramètres du projet → Paramètres de base, ou en exécutant :

apidog project list

N'importe quel agent de codage capable d'exécuter des commandes shell fonctionne ici : Claude Code, Cursor, Codex, et d'autres. La CLI ne se soucie pas de savoir qui l'appelle ; elle se soucie uniquement que les commandes et les charges utiles soient correctes. Ce qui nous amène à la règle unique qui rend l'ensemble fiable.

Le rituel d'écriture qu'un agent doit suivre

Les commandes de documentation qui créent des ressources prennent un fichier JSON. Votre agent ne devrait jamais construire ce JSON à la main de mémoire. Les noms de champs inventés par le modèle sont la cause numéro un des échecs d'exécution. La CLI fournit le schéma exact pour chaque écriture, et la séquence correcte est toujours la même en quatre étapes :

# 1. Demandez à la CLI à quoi ressemble la charge utile
apidog cli-schema get doc-create

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

# 3. Validez avant d'écrire (détecte un champ manquant localement)
apidog cli-schema validate doc-create --file ./doc.json

# 4. Seulement maintenant, exécutez la vraie commande
apidog doc create --project <projectId> --file ./doc.json

Intégrez cette boucle aux instructions de l'agent. Cela transforme "le modèle a inventé un champ" en "le validateur l'a rejeté sur ma machine", ce qui est la différence entre une exécution propre et un échec de build. Voici un bloc de règles que vous pouvez coller directement dans l'invite système d'un agent ou dans un fichier CLAUDE.md / .cursorrules :

Règles Apidog CLI :
- Ne jamais écrire manuellement une charge utile JSON. Exécutez d'abord `apidog cli-schema get ` et construisez à partir de ce schéma.
- Validez chaque fichier avec `apidog cli-schema validate  --file ` avant toute création ou mise à jour.
- Toujours passer --project  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 choisissez pas de solution de contournement.

Ces cinq lignes sont ce qui sépare un agent qui livre des documents de manière fiable d'un agent qui devine des charges utiles dans le vide.

Étape 1 : Créer la référence à partir des points de terminaison et des schémas

Dans Apidog, votre référence d'API est générée à partir des points de terminaison et des schémas de données du projet. Le premier travail de l'agent est donc de les créer. Supposons que vous lui disiez :

« Ajoutez un point de terminaison `POST /refunds` qui prend un ID de commande et un montant, et documentez ses réponses de succès et d'erreur de validation. »

L'agent crée d'abord le modèle de données réutilisable, puis le point de terminaison qui y fait référence. L'exécution de `apidog cli-schema get schema-create` montre qu'un schéma de données prend un `name` et un objet `jsonSchema` standard. L'agent écrit donc quelque chose comme `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" }
    }
  }
}

Validez et créez :

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json

Maintenant, le point de terminaison. Le schéma `endpoint-create` requiert `method` et `path`, et vous permet de référencer le modèle de données que vous venez de créer avec un `$ref` au format `#/definitions/{schemaId}`. L'agent écrit `refunds-endpoint.json` :

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

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

La documentation de référence pour `/refunds` existe maintenant, rendue à partir de la même définition que votre équipe édite. Il n'y a pas d'étape séparée "exporter la documentation" pour la référence ; elle est en ligne dans le projet dès que le point de terminaison est intégré. C'est l'avantage d'une source axée sur les schémas : la référence ne peut pas dériver, car elle *est* le schéma.

Étape 2 : Rédiger les guides, pas seulement la référence

Une référence générée à partir de schémas n'est que la moitié d'une bonne documentation. L'autre moitié est la prose : une page de démarrage, une procédure d'authentification, une note de migration. Dans Apidog, celles-ci résident dans l'arborescence des documents du projet sous forme de documents Markdown, gérés par le groupe de commandes doc.

Le schéma `doc-create` ne requiert qu'un `name` ; `content` contient le Markdown, et `folderId` le place dans l'arborescence (`0` est la racine). Ainsi, un guide de démarrage rapide rédigé par l'agent devient `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
}

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json

C'est là que l'agent fait ses preuves. Demandez-lui de « rédiger un guide de démarrage rapide qui accompagne un nouveau développeur de la clé API au premier remboursement », et il rédigera le Markdown, l'enveloppera dans la charge utile attendue par le schéma, validera et créera le document. Pas de navigateur, pas de copier-coller. Parce que le contenu est un simple champ de chaîne de caractères, l'agent peut rédiger un guide aussi long ou détaillé que la tâche l'exige.

Étape 3 : Publier le site de documentation

Avec la référence et les guides en place, l'agent peut également publier depuis le terminal. Deux groupes de commandes gèrent cela, et une distinction de nommage déroute constamment les gens :

doc : un document Markdown à l'intérieur de l'arborescence API du projet (ce que vous avez créé à l'étape 2).
docs-site : le site de documentation hébergé et public.
shared-doc : un lien partageable à transmettre à un partenaire, et non un site complet.

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

Utilisez `docs-site` lorsque vous souhaitez un site public défini depuis le terminal, et `shared-doc` lorsque vous avez juste besoin d'un lien à envoyer à quelqu'un. Étant donné que les deux sont des commandes, la publication devient une étape scriptée que l'agent exécute après chaque modification de document ; le site hébergé reflète la mise à jour dès que la commande est renvoyée.

Étape 4 (facultatif) : Exporter une copie portable

Parfois, vous souhaitez la documentation sous forme de fichier : une page HTML à héberger ailleurs, du Markdown pour un générateur de site statique, ou de l'OpenAPI à transmettre en aval. La commande `export` produit les trois :

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

Si votre projet contient plusieurs services et que vous ne souhaitez en documenter qu'une partie, `apidog export --help` affiche les drapeaux `--scope`, `--api-ids` et `--folder-ids` pour affiner la sortie. Un seul projet peut ainsi livrer un fichier de documentation par service.

Un exemple complet, de bout en bout

Voici la boucle complète sous forme d'une requête en langage clair et les commandes qu'un agent exécute pour y répondre.

Vous : « 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, suivant ses règles, exécute :

# 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 points de terminaison
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Rédiger le guide d'idempotence comme un document Markdown
apidog doc create --project $PID --file ./idempotency-guide.json

# Publier
apidog docs-site create --project $PID --file ./docs-site.json

Vous examinez le différentiel résultant, et le service de paiement est documenté et en ligne. Ce qui était auparavant un après-midi de changement de contexte est devenu une requête et une révision.

Intégrez-le dans une boucle d'agent ou une CI

Puisque chaque étape est une commande, tout le flux s'intègre dans la CI ou dans la boucle de tâches d'un agent. Une étape minimale qui régénère et valide votre référence Markdown à chaque push :

- 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

Pour une vue plus complète de l'exécution d'un agent avec la CLI de bout en bout, consultez De la PRD à la boucle de test et Comment configurer 5 agents IA pour construire une API complète. Le schéma est le même dans les deux cas : décrivez l'intention, laissez l'agent la traduire en appels CLI validés, examinez le résultat.

Une note sur les permissions

L'écriture dans un projet via un agent peut être contrôlée. Si une commande `create` est bloquée, le projet a désactivé les "External AI Edit Permissions" pour cette branche. Vous avez deux options honnêtes : activer la permission d'édition directe dans Paramètres du projet → Paramètres des fonctionnalités → Paramètres des fonctionnalités IA (client Apidog 2.8.32+), ou faire travailler l'agent sur une branche IA isolée et ouvrir une demande de fusion. Le guide complémentaire sur la mise à jour de votre spécification API décrit en détail le flux de branche IA, et il s'applique de la même manière lorsque l'agent est en train de créer de la documentation sur une branche protégée.

Pièges courants

L'agent a construit le JSON à la main. C'est la principale cause d'échec. Appliquez `cli-schema get` → `cli-schema validate` → `create` dans les instructions de l'agent afin qu'il travaille à partir du schéma réel, et non d'un schéma deviné.
ID de projet manquant. Chaque appel `doc`, `docs-site` et `export` nécessite `--project`, l'ID provenant des paramètres, et non le nom de projet lisible. La plupart des rapports d'"erreur" sont dus à cela.
Confusion entre `doc`, `docs-site` et `shared-doc`. Ce sont trois choses différentes : une page Markdown dans l'arborescence, un site hébergé et un lien de partage. Demandez à l'agent de confirmer ce que la tâche signifie avant qu'il n'écrive.
Jeton non défini dans la CI. `apidog login` stocke le jeton sur la machine qui l'exécute. Un nouveau runner de CI n'en a pas, alors exécutez `login --with-token` dans le même job avant toute commande, et conservez le jeton dans un secret.
Un `$ref` qui ne pointe nulle part. Lorsqu'un point de terminaison référence un modèle de données avec `#/definitions/{schemaId}`, ce schéma doit exister au préalable. Créez les schémas avant les points de terminaison qui les utilisent.

FAQ

Quels agents IA peuvent piloter la CLI Apidog ? Tout agent capable d'exécuter des commandes shell : Claude Code, Cursor, Codex, et les agents de codage similaires. La CLI est agnostique à l'agent ; elle n'a besoin que de commandes correctes et de charges utiles valides.

Ai-je besoin d'un plan payant ? Non. Apidog n'est pas open source, mais le niveau gratuit plus `apidog-cli` couvre le flux de création et de publication décrit ici.

L'agent peut-il écraser des documents existants par accident ? `create` ajoute de nouvelles ressources. La modification des ressources existantes utilise `update`, qui se comporte différemment et nécessite ses propres garde-fous ; ceci est couvert dans le guide complémentaire sur la mise à jour de votre spécification API.

En quoi cela diffère-t-il d'un générateur de documents IA ? Les outils génériques de documentation IA produisent du texte à partir de votre code. Ceci produit une documentation structurée au sein de votre plateforme API (points de terminaison, schémas, guides et un site publié) à partir d'une source unique et vivante qui ne peut pas dériver de ce que votre équipe édite.

Pour conclure

Un agent capable d'exécuter la CLI Apidog peut prendre en charge la partie de la documentation que les gens reportent toujours : il crée les points de terminaison, rédige les guides associés et publie le site. Le tout à partir d'une requête en langage clair, avec une validation de schéma protégeant chaque écriture. Votre rôle passe de la rédaction de documents à la révision d'un différentiel.

La seule règle qui rend cela fiable est le rituel d'écriture : obtenir le schéma, valider, puis créer. Donnez à votre agent cette boucle, le bloc de règles de cinq lignes ci-dessus, et un ID de projet, et la documentation cessera d'être une corvée qui traîne derrière le code. Téléchargez Apidog pour obtenir la CLI, ou lisez le guide complet de la CLI Apidog pour la référence complète des commandes.

bouton