DEV Community

Cover image for Les meilleurs outils CLI légers pour la documentation d'API
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Les meilleurs outils CLI légers pour la documentation d'API

Vous avez un fichier OpenAPI et vous voulez produire une documentation sans déployer de service, vous connecter à un portail ou ajouter une chaîne de build lourde. L'objectif : exécuter une commande sur votre spécification et obtenir soit un fichier Markdown, soit une page HTML autonome à héberger où vous voulez.

Essayez Apidog dès aujourd’hui

Cette sélection regroupe des outils à faible empreinte : un binaire, une commande npx ou un package npm. Ils lisent une spécification, génèrent une sortie, puis s'intègrent facilement à un terminal ou à une tâche CI. Certains produisent du Markdown pour votre site de documentation existant ; d'autres construisent directement un fichier HTML autonome.

Pour comparer des plateformes plus complètes, consultez ce tour d'horizon des meilleurs outils de documentation d'API REST. Pour comprendre exactement ce que les générateurs analysent, utilisez la spécification OpenAPI comme référence.

Qu'est-ce qui rend un outil CLI « léger » pour la documentation d'API ?

Un outil léger n'est pas forcément limité : il réduit surtout la friction entre votre fichier OpenAPI et votre documentation publiée.

Évaluez quatre critères :

  1. Installation minimale

    Un package npm ou un binaire est plus simple à maintenir qu'un framework avec runtime, bundler et plugins.

  2. Configuration facultative

    Dans le meilleur cas, vous passez openapi.yaml en entrée et obtenez un fichier en sortie.

  3. Sortie ciblée

    L'outil doit faire une chose clairement : convertir une spécification en Markdown ou en HTML.

  4. Exécution reproductible en CI

    Pas d'interface graphique ni de serveur persistant : la même commande doit fonctionner localement et dans votre pipeline.

Pour découvrir également des solutions hébergées, consultez la liste des outils de documentation d'API gratuits.

Widdershins

Widdershins est un convertisseur OpenAPI, Swagger 2 et AsyncAPI vers Markdown. Il ne démarre aucun serveur et ne génère pas de site : il produit un fichier .md, ce qui le rend pratique pour un dépôt Git et une CI.

Installation et génération 

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

Ajoutez ensuite api-docs.md à votre site statique, votre wiki ou votre dépôt de documentation.

Options utiles

Supprimez le front matter YAML :

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

Configurez les onglets de langages pour les exemples de code :

widdershins openapi.yaml \
  -o api-docs.md \
  --language_tabs 'shell:Shell' 'javascript:JavaScript' 'python:Python'
Enter fullscreen mode Exit fullscreen mode

À utiliser si : vous voulez versionner, comparer et réutiliser une documentation Markdown générée depuis la spécification.

Limite : Widdershins ne fournit ni thème, ni rendu HTML, ni console interactive. Vous devrez envoyer le Markdown dans un générateur de site ou un outil de publication.

OpenAPI Generator : générateurs de documentation

OpenAPI Generator est surtout utilisé pour créer des SDK, mais ses générateurs de documentation sont utiles si vous l'avez déjà dans votre outillage.

Deux sorties sont particulièrement adaptées :

  • markdown : génère un dossier de fichiers Markdown ;
  • html2 : génère une page HTML autonome.

Installation et génération 

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/
Enter fullscreen mode Exit fullscreen mode

L'enveloppeur npm télécharge un fichier JAR compatible avec le JDK lors de la première exécution. Les exécutions suivantes restent simples à automatiser dans un pipeline.

À utiliser si : vous générez déjà des clients avec OpenAPI Generator et souhaitez centraliser la génération de SDK et de documentation.

Limite : la sortie est basée sur des modèles et la première exécution est plus lourde qu'avec Widdershins.

Redocly CLI : build-docs

Pour générer rapidement une page HTML de référence propre et autonome, utilisez Redocly CLI et sa commande build-docs.

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Par défaut, la commande crée redoc-static.html.

Choisir le nom de sortie 

npx @redocly/cli build-docs openapi.yaml --output api.html
Enter fullscreen mode Exit fullscreen mode

Vous pouvez maintenant ouvrir api.html localement ou le déposer sur un hébergement statique.

Exemple CI 

npx @redocly/cli build-docs openapi.yaml --output public/api.html
Enter fullscreen mode Exit fullscreen mode

Ajoutez ensuite le dossier public/ à l'artefact ou au déploiement de votre CI.

À utiliser si : vous voulez une documentation HTML partageable avec une seule commande et sans installer globalement d'outil.

Limite : la sortie est une page de référence unique, pas un portail documentaire multi-pages. Pour comparer des solutions proches, consultez les alternatives à Redocly et les alternatives à Scalar.

Slate

Slate est différent des autres outils de cette liste : il ne convertit pas directement OpenAPI en documentation. C'est un générateur de site statique pour une documentation API écrite en Markdown.

Il produit une mise en page classique à trois colonnes :

  • navigation ;
  • contenu ;
  • exemples de code.

Slate utilise Middleman et nécessite donc Ruby.

Construire un site Slate

Après avoir cloné le dépôt Slate et installé ses dépendances :

bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Le site statique est généré dans build/. Vous pouvez publier ce dossier sur n'importe quel hébergeur statique.

Combiner Widdershins et Slate

Une approche pratique consiste à générer le contenu depuis OpenAPI, puis à le rendre avec Slate :

widdershins openapi.yaml -o source/index.html.md
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

À utiliser si : vous voulez rédiger et organiser manuellement une documentation API narrative tout en conservant une mise en page spécialisée.

Limite : Slate est l'option la plus lourde ici : il demande une chaîne d'outils Ruby et ne lit pas OpenAPI directement.

Apidog CLI : export et documentation

Les outils précédents couvrent chacun une étape : conversion, rendu ou publication. Si votre API existe déjà dans un projet plutôt que dans un fichier YAML isolé, les relier peut ajouter de la friction.

Le binaire apidog-cli est le compagnon en ligne de commande d'Apidog. Il permet d'exporter un projet API en Markdown ou HTML sans construire un pipeline séparé.

Installer et s'authentifier 

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

Exporter la documentation

Exportez directement la documentation du projet en Markdown :

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

Ou exportez-la en HTML :

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

Gérer les ressources de documentation

La CLI permet aussi de lister les documents Markdown et les sites documentaires d'un projet :

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

Les résultats sont structurés en JSON, ce qui facilite leur consommation par une étape CI, un script ou un agent.

Pour le détail des commandes disponibles, consultez le guide complet de l'Apidog CLI.

Apidog n'est pas open source et la CLI communique avec un projet hébergé. Elle ne remplace pas un outil de linting OpenAPI ou de règles de style comme Redocly et Spectral. Son intérêt est d'offrir un chemin intégré entre un projet API maintenu et une exportation Markdown ou HTML partageable.

Pour le flux Markdown en particulier, voir Générateur de documentation API avec exportation Markdown.

Comment choisir

Choisissez l'outil selon votre entrée et le format de sortie attendu.

Outil Idéal pour Installation Open source ? Sortie
Widdershins Spécification vers Markdown, rapidement npm i -g widdershins Oui (MIT) Markdown
OpenAPI Generator Documentation à 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 documentation rédigé à la main Ruby + Bundler Oui (Apache 2.0) Site statique
Apidog CLI Exporter depuis un projet API npm i -g apidog-cli Non (offre gratuite) Markdown ou HTML

En pratique :

  • vous avez une spécification brute et voulez du Markdown versionnable : Widdershins ;
  • vous voulez rapidement une page HTML autonome : Redocly CLI ;
  • vous générez déjà des SDK : OpenAPI Generator ;
  • vous rédigez une documentation structurée à la main : Slate ;
  • votre source est un projet API hébergé : Apidog CLI.

Pour une vue d'ensemble des options disponibles, consultez les outils de documentation API gratuits.

En résumé

Commencez par l'outil le plus petit qui produit le format dont vous avez besoin :

  • widdershins pour convertir rapidement OpenAPI en Markdown ;
  • redocly build-docs pour produire une page HTML autonome ;
  • OpenAPI Generator si votre workflow génère déjà des SDK ;
  • Slate si votre documentation est principalement éditoriale ;
  • apidog export si votre API est déjà gérée dans un projet Apidog.

Si votre API est maintenue dans un projet, téléchargez Apidog et testez apidog export dans votre CI afin de reconstruire la documentation à chaque changement d'API.

Top comments (0)