Les documents API deviennent obsolètes dès que quelqu'un modifie une spécification et oublie de régénérer la référence. La solution est d'arrêter de traiter la documentation comme une étape manuelle. Si vous pouvez produire des documents avec une seule commande, vous pouvez intégrer cette commande dans la CI et la laisser s'exécuter à chaque fusion.
Le faire depuis le terminal présente d'autres avantages. Les commandes sont scriptables, elles laissent un diff que vous pouvez examiner, et un agent IA ou un runner CI peut les déclencher sans que personne n'ouvre un navigateur. Pas de clics d'interface graphique, pas de « vous avez pensé à cliquer sur exporter ».
Ce guide explore d'abord la voie ouverte générale : transformer un fichier OpenAPI en une référence HTML autonome ou un fichier Markdown avec une seule commande. Ensuite, il approfondit la voie de la CLI Apidog, qui extrait votre documentation directement d'un projet en direct afin que la source de vérité et la sortie restent synchronisées. Si vous souhaitez plus d'informations sur le paysage, consultez notre récapitulatif des meilleurs outils de documentation d'API REST et des outils de documentation d'API gratuits à connaître.
Vous avez besoin d'une seule chose pour suivre : un fichier OpenAPI 3.x. La plupart de ces commandes acceptent indifféremment openapi.yaml ou openapi.json.
Construire une référence HTML avec Redocly CLI
Redocly CLI est le moyen le plus rapide de transformer une description OpenAPI en une page HTML soignée et autonome. Il rend votre spécification avec Redoc et écrit tout (styles, script et contenu) dans un seul fichier que vous pouvez héberger n'importe où ou envoyer par e-mail à un coéquipier.
Installez-le globalement, ou ignorez l'installation et exécutez-le avec npx :
npm install @redocly/cli -g
Puis pointez-le vers votre spécification :
redocly build-docs openapi.yaml
Par défaut, cela écrit redoc-static.html dans le répertoire actuel. Ouvrez ce fichier dans un navigateur et vous aurez une référence API complète à trois panneaux. Pour contrôler le nom de fichier ou le chemin, utilisez --output :
redocly build-docs openapi.yaml --output docs/index.html
C'est tout le flux de travail. Un fichier d'entrée, une commande, un artefact HTML. Cela fonctionne avec les descriptions Swagger 2.0 et OpenAPI 3.0/3.1, de sorte que la plupart des spécifications existantes sont rendues sans modifications. Le compromis est la portée : build-docs vous donne une page de référence et rien d'autre. Les guides détaillés, les tutoriels et les pages de démarrage rapide se trouvent en dehors de cela.
Générer du Markdown avec Widdershins
Parfois, vous ne voulez pas de HTML. Vous voulez du Markdown que vous pouvez intégrer dans un site de documentation, un générateur de site statique ou le dossier docs/ d'un dépôt. Widdershins convertit une définition OpenAPI, Swagger ou AsyncAPI en Markdown compatible avec Slate.
Installez-le depuis npm :
npm install -g widdershins
Convertissez ensuite votre spécification, en envoyant la sortie vers un fichier avec -o :
widdershins openapi.yaml -o api.md
Omettez -o et Widdershins imprimera sur la sortie standard, ce qui est pratique si vous voulez le rediriger ailleurs. Vous pouvez également activer les onglets de langue pour les exemples de code :
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins est une bonne solution lorsque votre pipeline de documentation est axé sur le Markdown. Si vous construisez un flux d'exportation Markdown plus large, notre guide sur l'utilisation d'un générateur de documentation API avec exportation Markdown couvre les outils associés. Le problème avec Redocly et Widdershins est le même : ils lisent un fichier statique. Si votre définition d'API se trouve dans un outil de conception et diverge du fichier sur disque, vous documentez la spécification d'hier.
Documenter à partir d'un projet en direct avec l'APIDog CLI
C'est là que la voie intégrée porte ses fruits. Apidog n'est pas open source, mais son offre gratuite associée à apidog-cli vous offre une alternative à l'assemblage d'outils séparés : vos points d'extrémité, schémas et documents écrits vivent tous dans un seul projet, et la CLI exporte depuis ce projet à la demande. Rien ne diverge, car l'exportation lit la même source que votre équipe modifie.
Installez la CLI depuis npm :
npm install -g apidog-cli
Si vous configurez pour la première fois, notre guide d'installation de l'Apidog CLI couvre les versions de Node et la configuration du PATH. Ensuite, authentifiez-vous une fois avec un jeton d'accès personnel :
apidog login --with-token <TOKEN>
Le jeton est stocké, vous n'avez donc pas à le transmettre à chaque appel. À partir de là, tout s'exécute avec un ID de projet. Ajoutez --help à n'importe quelle commande pour voir ses drapeaux exacts avant de l'exécuter.
Importer une spécification dans le projet
Si votre API réside déjà dans un fichier OpenAPI, importez-le dans un projet afin que la CLI ait quelque chose à exporter :
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import accepte les formats OpenAPI 3.x, Swagger 2.0, Postman et Apidog, vous pouvez donc importer une collection Postman ou une exportation Apidog existante de la même manière. Une fois la spécification importée, elle devient la source en direct à partir de laquelle tout le reste est lu.
Exporter des documents lisibles par l'homme
C'est la commande principale. apidog export écrit OpenAPI, HTML, Markdown ou Postman, alors exécutez --help d'abord pour voir le format exact et les drapeaux de sortie de votre version, puis exportez la documentation du projet vers Markdown :
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
Ouvrez api-docs.md et vous avez une référence complète générée à partir de l'état actuel du projet. Vous voulez du HTML à la place ? Changez un seul drapeau :
apidog export --project <projectId> --format html --output ./api-docs.html
Vous pouvez également exporter vers OpenAPI lorsque vous souhaitez une spécification portable à transmettre en aval :
apidog export --project <projectId> --format openapi --output ./openapi.json
Si votre projet contient plusieurs services et que vous ne souhaitez en documenter qu'une partie, l'exportation prend en charge la réduction de la portée. Vérifiez apidog export --help pour les drapeaux de portée et d'ID dans votre version, car un seul projet peut ainsi livrer un fichier de documentation par service.
Gérer les guides écrits, pas seulement la référence
Une référence générée à partir de votre schéma n'est que la moitié de l'histoire. L'autre moitié est la prose : guides de démarrage, tutoriels d'authentification, notes de migration. Dans Apidog, ceux-ci vivent dans l'arborescence de documentation du projet en tant que documents Markdown, et la CLI les gère avec le groupe de commandes doc.
Commencez par lire l'aide du groupe afin de travailler avec les drapeaux exacts de votre version :
apidog doc --help
apidog doc list --project <projectId>
À partir de là, le flux est le même que pour tout le reste dans la CLI : exécutez la commande sur votre projet, lisez le résultat JSON et suivez les agentHints.nextSteps qu'il renvoie. Lorsqu'une commande attend une charge utile JSON, la CLI peut imprimer le schéma qu'elle attend et valider votre fichier par rapport à celui-ci avant d'envoyer quoi que ce soit, de sorte que vous détectez un champ manquant sur votre machine au lieu d'un appel échoué. Vérifiez apidog cli-schema --help pour la sous-commande de validation exacte.
Publier un site de documentation
Lorsque la référence et les guides sont prêts, vous pouvez également gérer la documentation publiée depuis le terminal. Deux commandes le couvrent, et lire leur aide d'abord permet d'économiser un drapeau deviné :
apidog docs-site --help
apidog shared-doc --help
Une note de nommage qui déroute les gens : un doc est un document Markdown à l'intérieur de l'arborescence de l'API du projet, docs-site gère le site de documentation public hébergé, et shared-doc gère les liens de documentation partageables. Utilisez docs-site lorsque vous voulez un site public défini depuis le terminal plutôt que construit par clics dans une interface utilisateur, et shared-doc lorsque vous voulez simplement un lien à donner à un partenaire. L'avantage est que la publication devient une étape scriptée : lorsque votre spécification change, vous réimportez ou modifiez le projet, puis exécutez à nouveau la commande de publication, et la documentation hébergée reflète la mise à jour.
Intégrer à la CI
La raison d'exécuter tout cela depuis la CLI est la répétabilité. Une fois que les commandes fonctionnent localement, elles fonctionnent dans un pipeline. Une étape minimale de GitHub Actions qui régénère et commit votre référence Markdown à chaque push ressemble à ceci :
- 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
Remplacez par redocly build-docs ou widdershins et la forme est identique. La documentation cesse d'être une tâche fastidieuse dont quelqu'un doit se souvenir et devient un artefact de build qui se régénère lui-même. Pour la référence complète des commandes, consultez le guide complet de l'Apidog CLI.
Pièges courants
ID de projet incorrect ou manquant. Chaque appel Apidog export, doc et docs-site nécessite --project <projectId>. L'ID se trouve dans les paramètres du projet, et non dans le nom de projet lisible par l'homme. Si une commande échoue en se plaignant du projet, c'est presque toujours la cause.
Jeton non défini dans la CI. apidog login stocke le jeton sur la machine qui l'exécute. Dans un runner CI vierge, aucun jeton n'est stocké, vous devez donc exécuter login --with-token dans le même job avant toute exportation. Stockez le jeton en tant que secret, jamais dans le fichier de workflow.
Exportations de fichiers obsolètes. Redocly et Widdershins lisent tout fichier que vous leur donnez. Si votre openapi.yaml est obsolète, votre documentation l'est aussi. C'est précisément la dérive que la voie Apidog évite en exportant depuis le projet en direct au lieu d'un fichier sur le disque.
Deviner les drapeaux au lieu de lire --help. Les drapeaux exacts pour export, doc, docs-site et shared-doc peuvent varier selon la version de la CLI. Exécutez apidog <commande> --help et travaillez à partir de ce qu'il affiche plutôt qu'un drapeau dont vous vous souvenez à moitié. Cela prend deux secondes et évite un build échoué.
Conclusion
Documenter une API depuis le terminal revient à choisir la bonne sortie. Optez pour Redocly CLI lorsque vous souhaitez une référence HTML autonome, Widdershins lorsque vous souhaitez du Markdown pour un site de documentation, et l'Apidog CLI lorsque vous souhaitez une référence, des guides écrits et un site publié, le tout exporté depuis une source unique et en direct. Cette dernière option est celle qui garantit l'exactitude de votre documentation, car l'exportation et ce que votre équipe modifie proviennent du même projet.
Chaque commande ici est scriptable, ce qui signifie que chacune d'elles a sa place dans la CI. Configurez-le une fois et votre documentation se régénérera à chaque modification. Téléchargez Apidog pour obtenir la CLI et essayer le flux d'exportation sur votre propre projet, ou lisez-en plus sur la façon dont Apidog s'intègre dans un flux de travail API-first.