DEV Community

Cover image for Outils en ligne de commande open source gratuits pour la documentation d'API
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Outils en ligne de commande open source gratuits pour la documentation d'API

Lorsque vous automatisez la génération de documentation API dans votre CI, la licence compte autant que le rendu final. Un outil open source vous permet d’auditer le code, de forker le projet si nécessaire, de versionner la sortie et d’héberger vos documents sans dépendre d’un fournisseur ou d’un nombre de sièges.

Essayez Apidog dès aujourd’hui

Cette sélection regroupe des outils de documentation API exécutables en ligne de commande. Ils lisent une spécification OpenAPI ou Swagger et génèrent du Markdown, une page HTML statique ou un site de documentation complet que vous pouvez héberger vous-même.

Chaque outil présenté est disponible sur GitHub sous une licence permissive — MIT ou Apache 2.0 — et peut être utilisé sans compte. Pour comparer aussi les plateformes avec interface graphique, consultez les meilleurs outils de documentation API REST. Votre point de départ reste une spécification OpenAPI valide.

Note : Apidog est cité plus loin comme alternative freemium, mais ce n’est pas un outil open source. Cette distinction est indiquée explicitement dans la section concernée.

Qu’est-ce qui rend un outil de documentation CLI réellement open source ?

Un outil n’est pas open source uniquement parce qu’il est gratuit à télécharger. Pour l’intégrer durablement à votre pipeline, vérifiez ces trois points.

1. Une licence permissive

Les licences MIT et Apache 2.0 autorisent l’utilisation, la modification et la redistribution commerciale du code.

  • MIT : licence courte et permissive.
  • Apache 2.0 : ajoute une concession de brevet explicite, souvent appréciée par les équipes juridiques.

Les outils open source listés ci-dessous utilisent l’une de ces licences.

2. Une sortie auto-hébergeable

Le générateur doit produire des fichiers que vous possédez :

  • Markdown à committer dans votre dépôt ;
  • page HTML autonome ;
  • dossier HTML, CSS et JavaScript pour un hébergement statique.

Vous pouvez ensuite publier ces fichiers sur GitHub Pages, S3, Cloudflare Pages ou un serveur Nginx.

3. Un projet maintenu ou forkable

Avant de standardiser un outil, vérifiez notamment :

  • les commits récents ;
  • les issues ouvertes ;
  • l’activité des forks ;
  • la compatibilité avec votre version d’OpenAPI.

Même un dépôt archivé peut rester utilisable si votre équipe peut maintenir un fork.

Pour une comparaison orientée coût entre solutions open source et freemium, consultez les outils gratuits de documentation API.

Redocly CLI

Redocly CLI est une option directe pour produire une référence API HTML autonome à partir d’un fichier OpenAPI. Le CLI et le moteur Redoc sont open source sous licence MIT ; certaines fonctions de portail hébergé appartiennent à l’offre commerciale Redocly.

Générez une page HTML avec build-docs :

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

Vous obtenez un fichier unique que vous pouvez tester localement :

open api-docs.html
Enter fullscreen mode Exit fullscreen mode

Puis publiez-le sur n’importe quel hébergeur statique. Cette approche fonctionne également hors ligne une fois le package disponible dans le cache npm.

Aperçu de Redocly CLI

À choisir si :

  • vous voulez une référence API propre dans un seul fichier HTML ;
  • vous souhaitez une intégration CI minimale ;
  • vous devez auto-héberger la sortie.

Limites :

  • la sortie est une page unique ;
  • les options de personnalisation avancées sont davantage présentes dans l’offre payante.

Pour comparer les moteurs de rendu, consultez les alternatives à Redocly.

Widdershins

Widdershins est un convertisseur MIT qui transforme des spécifications OpenAPI 3, Swagger 2 ou AsyncAPI en Markdown. Il ne génère pas un site : il produit du contenu versionnable que vous pouvez intégrer à votre propre chaîne de publication.

Installation et conversion :

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

Le fichier généré peut être relu dans une pull request, adapté manuellement, puis rendu par un générateur de site statique.

Quelques options utiles :

# Supprimer le front matter généré
widdershins openapi.yaml --omitHeader -o api-docs.md

# Définir les onglets de langages pour les exemples
widdershins openapi.yaml \
  --language_tabs 'javascript:JavaScript' 'python:Python' \
  -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

Aperçu de Widdershins

À choisir si :

  • vous voulez du Markdown généré et versionné ;
  • vous utilisez déjà un générateur de site ;
  • vous souhaitez séparer la conversion OpenAPI du rendu visuel.

Limite : Widdershins ne fournit ni thème ni site HTML. Il représente donc une étape dans un pipeline, pas le pipeline complet.

OpenAPI Generator

OpenAPI Generator est un projet communautaire sous licence Apache 2.0, issu d’un fork de Swagger Codegen en 2018. Il est surtout connu pour générer des SDK, mais il sait également produire de la documentation.

Installez le CLI :

npm install -g @openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Générez du Markdown :

openapi-generator-cli generate \
  -g markdown \
  -i openapi.yaml \
  -o docs/
Enter fullscreen mode Exit fullscreen mode

Ou générez une page HTML autonome :

openapi-generator-cli generate \
  -g html2 \
  -i openapi.yaml \
  -o docs-html/
Enter fullscreen mode Exit fullscreen mode

Aperçu d’OpenAPI Generator

À choisir si :

  • vous générez déjà des SDK clients ;
  • vous voulez réutiliser le même outil pour les SDK et les documents ;
  • votre organisation privilégie Apache 2.0.

Limites :

  • le wrapper npm télécharge un JAR Java lors de la première exécution ;
  • les modèles de documentation sont volontairement simples ;
  • pour un besoin limité à une page de documentation, un outil plus léger peut suffire.

Swagger Codegen

Swagger Codegen est le générateur historique de l’écosystème Swagger, sous licence Apache 2.0 et maintenu par SmartBear. Pour la documentation, il propose notamment :

  • html pour une référence statique ;
  • dynamic-html pour un site interactif léger.

Installation et génération HTML :

npm install -g swagger-codegen-cli

swagger-codegen-cli generate \
  -i openapi.yaml \
  -l html \
  -o docs/
Enter fullscreen mode Exit fullscreen mode

Aperçu de Swagger Codegen

À choisir si :

  • votre équipe utilise déjà Swagger Codegen ;
  • vous voulez conserver une chaîne d’outils homogène ;
  • vous générez aussi des stubs ou SDK avec Swagger.

Limites :

  • l’outil s’appuie sur Java ;
  • son évolution est plus lente que celle d’OpenAPI Generator ;
  • pour une nouvelle installation, OpenAPI Generator est généralement le choix communautaire le plus actif.

Docusaurus avec le plugin OpenAPI

Pour construire un portail complet plutôt qu’une simple référence, utilisez Docusaurus. Ce générateur de site statique sous licence MIT rend du Markdown et du MDX. Le plugin docusaurus-openapi-docs, également sous licence MIT, ajoute la génération de pages de référence depuis une spécification OpenAPI.

Créez un site Docusaurus :

npx create-docusaurus@latest my-docs classic
cd my-docs
Enter fullscreen mode Exit fullscreen mode

Installez le plugin :

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
Enter fullscreen mode Exit fullscreen mode

Après avoir configuré le chemin vers votre spécification dans la configuration Docusaurus, générez les pages :

npm run docusaurus gen-api-docs all
Enter fullscreen mode Exit fullscreen mode

Le plugin convertit votre fichier OpenAPI en pages MDX intégrées à la navigation du site, avec un panneau d’essai des endpoints.

Aperçu de Docusaurus avec le plugin OpenAPI

À choisir si :

  • vous avez besoin d’un portail de documentation complet ;
  • vous voulez publier des guides, tutoriels et références API au même endroit ;
  • vous gérez des versions de documentation ;
  • vous voulez auto-héberger un site statique.

Limite : cette solution demande plus de configuration : projet React, dépendances npm, configuration du plugin et build du site.

Slate

Slate est une solution historique pour les documentations API en trois colonnes :

  • navigation à gauche ;
  • documentation au centre ;
  • exemples de code à droite.

Slate est sous licence Apache 2.0 et repose sur Middleman, donc sur une chaîne d’outils Ruby. Contrairement aux outils précédents, il ne lit pas directement OpenAPI : vous rédigez ou générez du Markdown, puis Slate produit le site statique.

Après avoir cloné votre fork Slate et exécuté bundle install :

bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

Le site compilé est écrit dans build/, prêt à être déployé.

Un pipeline courant consiste à combiner Widdershins et Slate :

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

À choisir si :

  • vous voulez une documentation narrative et éditorialisée ;
  • vous appréciez la mise en page API à trois colonnes ;
  • vous souhaitez contrôler précisément le Markdown final.

Limites :

  • le dépôt original est archivé, même si des forks restent actifs ;
  • Ruby et Bundler ajoutent une dépendance supplémentaire ;
  • l’approche est moins adaptée à une régénération brute et fréquente depuis OpenAPI.

Apidog CLI : parenthèse honnête, pas une entrée open source

Les outils précédents couvrent la conversion d’une spécification, son rendu et son hébergement. Si votre source de vérité est un projet API maintenu — avec endpoints, schémas et exemples — vous devrez souvent assembler ces étapes dans votre pipeline.

Aperçu d’Apidog CLI

Le binaire apidog-cli répond à ce cas d’usage, mais il faut être clair sur la licence : Apidog n’est pas open source. C’est une plateforme commerciale freemium avec un niveau gratuit, et son CLI travaille avec un projet hébergé plutôt qu’avec une spécification locale uniquement.

Exemple d’export :

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

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

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

Le CLI propose aussi apidog doc et apidog docs-site pour gérer des ressources de documentation depuis un script. La sortie structurée en JSON facilite son intégration dans une étape CI.

Consultez le guide complet d’Apidog CLI pour l’authentification et les commandes disponibles. Pour un workflow centré sur Markdown, consultez également le guide du générateur de documentation API avec export Markdown.

La distinction est simple :

  • les outils open source vous donnent du code, une sortie auto-hébergeable et aucune dépendance à un fournisseur ;
  • Apidog fournit un flux intégré depuis un projet hébergé vers des documents exportables, mais reste un produit freemium.

Comment choisir

Choisissez selon la sortie attendue et le niveau de contrôle nécessaire.

Outil Idéal pour Installation Open source ? Sortie
Redocly CLI Une page HTML soignée npx @redocly/cli Oui, MIT, open core HTML autonome
Widdershins Une spécification convertie en Markdown npm i -g widdershins Oui, MIT Markdown
OpenAPI Generator Documentation et SDK avec un même outil npm i -g @openapitools/openapi-generator-cli Oui, Apache 2.0 Markdown ou HTML
Swagger Codegen Équipes standardisées sur Swagger npm i -g swagger-codegen-cli Oui, Apache 2.0 HTML
Docusaurus + plugin OpenAPI Portail de documentation complet npx create-docusaurus Oui, MIT Site statique
Slate Documentation éditorialisée à trois colonnes Ruby + Bundler Oui, Apache 2.0 Site statique
Apidog CLI Export depuis un projet API maintenu npm i -g apidog-cli Non, freemium Markdown ou HTML

En pratique :

  • utilisez Redocly CLI pour publier rapidement une référence HTML ;
  • choisissez Widdershins pour du Markdown versionné ;
  • prenez OpenAPI Generator si vous générez aussi des SDK ;
  • restez sur Swagger Codegen si votre organisation l’utilise déjà ;
  • adoptez Docusaurus pour un portail complet avec guides et versioning ;
  • choisissez Slate pour une documentation fortement contrôlée par l’éditorial ;
  • utilisez Apidog CLI si votre documentation doit être exportée depuis un projet API hébergé.

Pour une sélection plus large incluant des options gratuites et freemium, consultez les outils gratuits de documentation API.

Conclusion

Le bon CLI de documentation API dépend de trois critères : la licence, le format de sortie et l’emplacement de votre source de vérité.

MIT et Apache 2.0 vous permettent d’utiliser, modifier et auto-héberger vos outils sans coût de licence. Commencez donc par l’outil le plus simple qui produit le résultat attendu :

  • Redocly CLI pour une page HTML ;
  • Widdershins pour du Markdown ;
  • OpenAPI Generator ou Swagger Codegen pour combiner documentation et SDK ;
  • Docusaurus pour un portail ;
  • Slate pour une documentation manuelle structurée.

Si votre API vit dans un projet maintenu plutôt que dans un fichier isolé, vous pouvez télécharger Apidog et tester apidog export dans votre pipeline CI. Gardez toutefois à l’esprit qu’il s’agit d’une plateforme freemium, et non d’un binaire open source.

Top comments (0)