DEV Community

Cover image for Comment documenter les API depuis la CLI
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment documenter les API depuis la CLI

Les documents d’API deviennent obsolètes dès qu’une spécification change sans régénération de la référence. Pour éviter cette dérive, traitez la documentation comme un artefact de build : si une commande la génère, exécutez cette commande dans votre CI à chaque fusion.

Essayez Apidog dès aujourd’hui

Le terminal rend ce flux reproductible : les commandes sont scriptables, les fichiers générés produisent des diffs vérifiables, et un runner CI ou un agent IA peut les lancer sans navigateur. Vous éliminez les clics manuels et les exportations oubliées.

Ce guide couvre deux approches :

  1. Générer une référence depuis un fichier OpenAPI avec Redocly CLI ou Widdershins.
  2. Exporter la documentation depuis un projet actif avec la CLI Apidog, afin de garder la source et la sortie synchronisées.

Pour comparer les options disponibles, consultez les meilleurs outils de documentation d’API REST et les outils de documentation d’API gratuits.

Pour suivre les exemples, préparez un fichier OpenAPI 3.x, par exemple openapi.yaml ou openapi.json.

Construire une référence HTML avec Redocly CLI

Redocly CLI génère une page HTML autonome à partir d’une spécification OpenAPI. Le fichier produit inclut les styles, les scripts et le contenu : vous pouvez l’héberger tel quel ou le partager localement.

Installez la CLI globalement :

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

Générez ensuite la documentation :

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Par défaut, Redocly crée redoc-static.html dans le répertoire courant. Pour définir le chemin de sortie :

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Le workflow est simple :

  1. Versionnez votre spécification OpenAPI.
  2. Exécutez build-docs.
  3. Publiez le fichier HTML généré.

Cette commande accepte Swagger 2.0 ainsi qu’OpenAPI 3.0 et 3.1. Elle convient pour une référence API, mais ne génère pas vos guides, tutoriels ou pages de démarrage rapide.

Générer du Markdown avec Widdershins

Si votre site de documentation ou votre dépôt utilise Markdown, Widdershins transforme une définition OpenAPI, Swagger ou AsyncAPI en Markdown compatible avec Slate.

Installez-le avec npm :

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

Convertissez votre spécification vers un fichier Markdown :

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

Sans -o, Widdershins écrit le résultat sur la sortie standard. Vous pouvez donc le rediriger vers un autre outil ou fichier.

Pour ajouter des onglets avec des exemples de code :

widdershins openapi.yaml \
  --language_tabs 'shell:cURL' 'python:Python' \
  -o api.md
Enter fullscreen mode Exit fullscreen mode

Widdershins est adapté aux pipelines centrés sur Markdown. Pour aller plus loin, consultez ce guide sur l’utilisation d’un générateur de documentation API avec exportation Markdown.

Attention : Redocly et Widdershins lisent un fichier local. Si openapi.yaml n’est plus à jour, votre documentation ne le sera pas non plus.

Documenter à partir d’un projet actif avec l’Apidog CLI

La CLI Apidog permet d’exporter la documentation depuis un projet Apidog plutôt que depuis un fichier local. Les endpoints, schémas et documents écrits vivent dans le même projet, puis la CLI exporte cet état à la demande.

Installez la CLI :

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Pour la configuration initiale, consultez le guide d’installation de l’Apidog CLI.

Authentifiez-vous ensuite avec un jeton d’accès personnel :

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Le jeton est stocké localement. Les commandes suivantes utilisent l’ID du projet. Avant d’exécuter une commande dans un script, vérifiez ses options avec --help.

Importer une spécification dans un projet

Si votre API existe déjà sous forme de fichier OpenAPI, importez-la dans un projet :

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

apidog import prend en charge OpenAPI 3.x, Swagger 2.0, Postman et Apidog. Après l’import, le projet devient la source depuis laquelle vous pouvez exporter les autres formats.

Exporter une documentation lisible

Utilisez apidog export pour générer des formats OpenAPI, HTML, Markdown ou Postman.

Commencez par vérifier les options disponibles dans votre version :

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Exportez ensuite la référence au format Markdown :

apidog export \
  --project <projectId> \
  --format markdown \
  --output ./api-docs.md
Enter fullscreen mode Exit fullscreen mode

Pour produire du HTML, modifiez uniquement le format et le fichier de sortie :

apidog export \
  --project <projectId> \
  --format html \
  --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

Pour récupérer une spécification OpenAPI portable :

apidog export \
  --project <projectId> \
  --format openapi \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

Si votre projet contient plusieurs services, consultez apidog export --help pour identifier les options de portée et d’ID disponibles dans votre version.

Gérer les guides écrits

Une référence générée depuis le schéma ne couvre pas les guides de démarrage, les tutoriels d’authentification ou les notes de migration. Dans Apidog, ces contenus sont des documents Markdown gérés dans l’arborescence de documentation du projet.

Listez les commandes et les documents disponibles :

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

Le flux recommandé est le suivant :

  1. Exécutez la commande sur le projet.
  2. Lisez la réponse JSON.
  3. Suivez les indications agentHints.nextSteps lorsqu’elles sont renvoyées.
  4. Validez les charges utiles JSON avant envoi lorsque la CLI fournit un schéma.

Pour vérifier les sous-commandes de validation disponibles :

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

Publier un site de documentation

La CLI inclut également des commandes pour gérer la documentation publiée et les liens partageables :

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

Les termes désignent des éléments différents :

  • doc : un document Markdown dans l’arborescence du projet ;
  • docs-site : le site public de documentation hébergé ;
  • shared-doc : les liens de documentation partageables.

Utilisez docs-site pour configurer ou publier un site depuis le terminal. Utilisez shared-doc pour produire un lien destiné à un partenaire ou à une équipe externe.

Intégrer la génération à la CI

L’intérêt principal de la CLI est la répétabilité. Une commande validée localement peut être exécutée dans votre pipeline.

Voici une étape GitHub Actions minimale qui exporte une référence Markdown :

- name: Regenerate API docs
  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

Vous pouvez appliquer la même structure avec Redocly ou Widdershins :

- name: Generate HTML API reference
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

L’objectif est de faire de la documentation un artefact généré à chaque modification de l’API, plutôt qu’une tâche manuelle à ne pas oublier.

Pour les commandes Apidog, consultez le guide complet de l’Apidog CLI.

Pièges courants

ID de projet incorrect ou manquant.

Les commandes Apidog comme export, doc et docs-site nécessitent --project <projectId>. Utilisez l’ID présent dans les paramètres du projet, pas son nom lisible.

Jeton absent dans la CI.

apidog login stocke le jeton sur la machine courante. Un runner CI démarre généralement vierge : exécutez donc apidog login --with-token dans le même job avant tout export. Stockez toujours le jeton dans un secret.

Spécification locale obsolète.

Redocly et Widdershins génèrent la documentation à partir du fichier fourni. Si ce fichier est ancien, la documentation le sera aussi.

Drapeaux devinés.

Les options de export, doc, docs-site et shared-doc peuvent varier selon la version de la CLI. Vérifiez systématiquement :

apidog <commande> --help
Enter fullscreen mode Exit fullscreen mode

Conclusion

Choisissez l’outil selon la sortie attendue :

  • Redocly CLI pour une référence HTML autonome ;
  • Widdershins pour du Markdown destiné à un site de documentation ;
  • Apidog CLI pour exporter une référence, des guides et un site depuis un projet actif unique.

Toutes ces approches sont scriptables. Ajoutez-les à votre CI, puis régénérez la documentation à chaque évolution de l’API.

Téléchargez Apidog pour obtenir la CLI et tester le flux d’exportation sur votre projet, ou découvrez comment Apidog s’intègre dans un workflow API-first.

Top comments (0)