Vous avez un fichier OpenAPI et vous voulez en tirer de la documentation. Vous ne voulez pas mettre en place un service, vous connecter à un portail ou ajouter une étape de construction qui tire la moitié de npm. Vous voulez une seule commande qui lit la spécification et vous fournit un fichier Markdown ou une seule page HTML que vous pouvez héberger n'importe où.
C'est à cela que sert cette liste. Chaque outil ici est petit : un seul binaire, une commande `npx` en une ligne, ou un package que vous installez une fois et oubliez. Ils démarrent rapidement, nécessitent peu ou pas de configuration, et font le travail de documentation sans traîner une plateforme complète derrière eux. Certains génèrent du Markdown que vous pouvez insérer dans un site de documentation existant. Certains génèrent un fichier HTML autonome. Tous s'exécutent en CI et dans un terminal, ce qui est l'essentiel.
Si vous voulez le champ plus large des plateformes de documentation, le tour d'horizon des meilleurs outils de documentation d'API REST couvre l'extrémité riche en GUI. Cet article est la version axée sur le terminal, à faible empreinte. Pour la référence officielle sur ce qu'un générateur de documentation lit, la spécification OpenAPI est la source de vérité que chaque outil ci-dessous analyse.
Qu'est-ce qui rend un outil CLI « léger » pour la documentation d'API
Léger ne signifie pas sous-puissant. Il s'agit d'empreinte et de friction. Quatre choses le déterminent.
Taille d'installation et dépendances. Un seul binaire ou un seul package npm est préférable à un framework. Si la génération d'une page de documentation signifie l'installation d'un environnement d'exécution de langage plus un bundler plus un système de plugins, ce n'est pas léger, quel que soit l'aspect de la sortie.
Démarrage et configuration. Les meilleurs d'entre eux lisent votre spécification et produisent une sortie sans aucune configuration. Vous pointez la commande vers `openapi.yaml` et obtenez un fichier. Tout ce qui nécessite un fichier de configuration avant de pouvoir fonctionner perd des points ici.
Sortie à but unique. Chaque outil ci-dessous fait une chose : spécification en entrée, documentation en sortie. Markdown ou HTML, rien d'autre d'ajouté. C'est ce qui les rend rapides et prévisibles dans un pipeline.
Fonctionne n'importe où. Pas d'interface graphique, pas de connexion pour les outils ouverts, pas de serveur à maintenir en vie. Cela fonctionne sur votre ordinateur portable et de la même manière dans une tâche de CI. Pour un ensemble plus large d'options gratuites, la liste des outils de documentation d'API gratuits propose les plateformes ; ceci est la part CLI de cela.
Maintenant les outils, du plus petit au plus grand.
Widdershins
Widdershins est à peu près aussi petit que possible. C'est un simple package npm qui convertit un fichier OpenAPI 3, Swagger 2 ou AsyncAPI en Markdown. C'est tout le travail. Il ne rend pas de site et ne fait pas fonctionner de serveur ; il vous donne un fichier `.md` et disparaît.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Le Markdown qu'il produit est compatible avec Slate, ce qui est important si vous prévoyez de l'intégrer ultérieurement dans un site statique. Drapeaux utiles : `--omitHeader` supprime le front-matter YAML, et `--language_tabs` contrôle les langages d'échantillons de code qui s'affichent.
Idéal pour : obtenir le contenu de la spécification au format Markdown que vous pouvez valider, comparer et insérer dans n'importe quel système de documentation. Limites honnêtes : le Markdown est tout ce que vous obtenez. Il n'y a pas de style, pas de panneau interactif "essayez-le", et pas de sortie hébergée. Widdershins est un convertisseur, pas un moteur de rendu, vous devez donc l'associer à quelque chose qui transforme le Markdown en un site.
OpenAPI Generator (générateurs de documentation)
OpenAPI Generator est surtout connu pour les SDK clients, mais il fournit également des générateurs de documentation, et ils sont pratiques lorsque vous n'avez qu'une spécification. Le générateur `markdown` écrit un dossier de Markdown ; le générateur `html2` écrit une seule page HTML autonome. Vous pouvez l'exécuter via l'enveloppeur npm sans installer Java vous-même.
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
L'enveloppeur npm télécharge toujours un jar supporté par JDK en arrière-plan, il est donc plus lourd que Widdershins lors de la première exécution. Après cela, c'est une génération en une seule commande.
Idéal pour : réutiliser un outil que vous utilisez peut-être déjà pour les SDK afin de générer également de la documentation, avec un choix entre Markdown et HTML autonome. Limites honnêtes : la sortie est simple et basée sur des modèles, et la première invocation télécharge un jar, ce n'est donc pas vraiment un binaire unique. Si vous n'avez besoin que de documentation et de rien d'autre, des options plus légères existent.
Redocly CLI (build-docs)
Si vous voulez une belle page HTML autonome à partir d'une seule commande, Redocly CLI est le chemin le plus court. La commande `build-docs` regroupe votre spécification en un seul fichier HTML autonome basé sur Redoc. Pas de serveur, pas de construction d'hébergement séparée ; vous obtenez un fichier que vous pouvez ouvrir, envoyer par e-mail ou déposer sur n'importe quel hôte statique.
npx @redocly/cli build-docs openapi.yaml
Par défaut, il écrit `redoc-static.html`. Changez le nom avec `--output` :
npx @redocly/cli build-docs openapi.yaml --output api.html
Comme il s'exécute via `npx`, vous n'avez même pas besoin de l'installer globalement pour l'essayer. Idéal pour : une référence soignée sur une seule page à partir d'une seule commande, avec un thème par défaut propre et aucune histoire d'hébergement à gérer. Limites honnêtes : la sortie est un seul fichier HTML, c'est donc une page de référence plutôt qu'un portail de documentation multi-pages, et les thèmes et aperçus plus riches se trouvent dans les niveaux payants de Redocly. Si vous le comparez à des moteurs de rendu similaires, les comparaisons d'alternatives à Redocly et d'alternatives à Scalar présentent les compromis.
Slate
Slate est l'exception ici : ce n'est pas un convertisseur de spécification en documentation, c'est un générateur de site statique pour les documentations API écrites à la main. Vous écrivez du Markdown, et Slate construit la disposition classique en trois colonnes (navigation, contenu et exemples de code côte à côte) en un site statique autonome. Il est alimenté par Middleman, il nécessite donc Ruby.
# after cloning the slate repo and installing dependencies
bundle exec middleman build
Cela écrit un site statique complet dans un dossier `build/` que vous pouvez héberger n'importe où. C'est là que Widdershins est utile : générez du Markdown à partir de votre spécification, puis laissez Slate le rendre, et vous obtenez du contenu basé sur la spécification dans la mise en page de Slate.
Idéal pour : des documentations API narratives, rédigées à la main, où vous souhaitez un contrôle éditorial sur la structure et le texte. Limites honnêtes : c'est l'option la plus lourde de cette liste car elle nécessite une chaîne d'outils Ruby, et elle ne lit pas OpenAPI seule ; vous lui donnez du Markdown. Si vos documents sont générés directement à partir d'une spécification et rarement édités à la main, un convertisseur seul est plus léger.
Apidog CLI (export + doc)
Les outils ouverts ci-dessus couvrent chacun une facette : convertir, rendre ou héberger. Si votre API existe déjà dans un projet au lieu d'un seul fichier YAML, les assembler crée des frictions. C'est là qu'intervient le binaire `apidog-cli`. C'est le compagnon en ligne de commande d'Apidog, et une exportation transforme un projet en Markdown ou HTML sans pipeline de build.
Installez-le depuis npm et authentifiez-vous avec un jeton :
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Ensuite, exportez la documentation du projet au format Markdown ou HTML en une seule commande :
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
La CLI gère également directement les ressources de documentation. `apidog doc` gère les documents Markdown du projet, et `apidog docs-site` gère les sites de documentation publiés, vous permettant ainsi de lister, créer et mettre à jour les documents depuis un script ou une tâche de CI :
apidog doc list --project <projectId>
apidog docs-site list --project <projectId>
La sortie est au format JSON structuré, ce qui facilite son insertion dans d'autres étapes ou sa transmission à un agent. Pour une vue d'ensemble complète des commandes, le guide complet de l'Apidog CLI vous guide à travers l'authentification, les projets et chaque groupe de commandes.
Voici le cadre honnête. Apidog n'est pas open source et ce n'est pas un binaire à usage unique ; c'est une plateforme freemium, et la CLI communique avec un projet hébergé. Il ne lint pas non plus votre OpenAPI ni n'impose de guide de style ; Redocly et Spectral le font. Ce que la CLI vous offre, c'est un chemin intégré d'un projet API maintenu vers du Markdown ou du HTML partageable, au lieu d'enchaîner manuellement un convertisseur, un moteur de rendu et un hôte. Si vous souhaitez spécifiquement le chemin d'exportation Markdown, l'article Générateur de documentation API avec exportation Markdown approfondit ce flux de travail.
Comment choisir
Faites correspondre l'outil à la forme de votre entrée et à la sortie dont vous avez besoin.
| Outil | Idéal pour | Installation | Open source ? | Sortie |
|---|---|---|---|---|
| Widdershins | Spéc. vers Markdown, rapide | npm i -g widdershins |
Oui (MIT) | Markdown |
| OpenAPI Generator | Docs à côté des SDK | npm i -g @openapitools/openapi-generator-cli |
Oui (Apache 2.0) | Markdown ou HTML |
| Redocly CLI | Une page HTML soignée | npx @redocly/cli |
Oui (MIT, open core) | HTML autonome |
| Slate | Site de docs fait main | Ruby + Bundler | Oui (Apache 2.0) | Site statique |
| Apidog CLI | Exportation depuis un projet en direct | npm i -g apidog-cli |
Non (offre gratuite) | Markdown ou HTML |
En bref : si vous avez une spécification brute et que vous voulez du Markdown à valider, utilisez Widdershins. Si vous voulez une page HTML partageable, `redocly build-docs` est le plus rapide. Si vous écrivez des documents à la main et que vous voulez une mise en page appropriée, Slate. Et si votre API existe déjà dans un projet et que vous voulez l'exportation et la gestion de documents dans une seule CLI, Apidog. Pour un aperçu gratuit de l'ensemble, le tour d'horizon des outils de documentation API gratuits rassemble tout cela.
En résumé
Les outils de documentation légers se résument à une règle : choisissez la chose la plus petite qui produit la sortie dont vous avez besoin. Widdershins et `redocly build-docs` couvrent la plupart des cas de spécification vers documentation en une seule commande. OpenAPI Generator en vaut la peine lorsque vous générez déjà des SDK. Slate justifie son empreinte plus lourde uniquement lorsque vous écrivez des documents à la main. Et lorsque votre API réside dans un projet réel plutôt qu'un fichier isolé, l'exportation `apidog-cli` vous donne du Markdown ou du HTML sans pipeline.
Si c'est votre cas, Téléchargez Apidog et essayez `apidog export` sur un projet ; il s'intègre parfaitement dans une tâche de CI afin que vos documents soient reconstruits chaque fois que l'API change.