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

Lorsque vous choisissez un outil pour générer votre documentation API, la licence fait partie de la décision. Un générateur open source signifie que vous pouvez lire le code, héberger vous-même la sortie, le forker s'il stagne, et ne jamais rencontrer de limite de sièges ou de péage sur une fonctionnalité que vous avez déjà livrée. Pour une tâche qui s'exécute à chaque build CI, cela compte autant que la qualité de la sortie.

Cette liste est la sélection open source des outils de documentation API qui s'exécutent en ligne de commande. Chaque outil ici est disponible en code source sous une vraie licence, MIT ou Apache 2.0, hébergé sur GitHub, et gratuit à utiliser sans compte requis. Vous le pointez vers un fichier OpenAPI ou Swagger et il vous fournit du Markdown, une page HTML statique, ou un site de documentation complet que vous possédez et hébergez vous-même.

Je signalerai la licence exacte et l'histoire de l'auto-hébergement pour chacun, car c'est la raison pour laquelle vous lisez un aperçu open source plutôt qu'un général. Si vous voulez un champ plus large, le récapitulatif des meilleurs outils de documentation API REST couvre également les plateformes GUI. La spécification OpenAPI est le format que chaque outil ci-dessous lit, donc une spécification valide est votre point de départ.

Une note honnête d'emblée. Apidog apparaît vers la fin, et ce n'est pas une entrée open source ; c'est une plateforme commerciale freemium. Je l'ai inclus uniquement comme une parenthèse étiquetée pour le cas où les outils open laisseraient un vide, et je serai explicite à ce sujet.

Qu'est-ce qui rend un outil de documentation CLI « open source »

Open source ne signifie pas seulement « gratuit à télécharger ». Pour les outils de documentation que vous intégrerez à un build, trois éléments déterminent si un outil est véritablement le vôtre.

Une vraie licence. MIT ou Apache 2.0 signifie que vous pouvez utiliser, modifier et redistribuer l'outil commercialement sans demander. Les deux sont approuvées par l'OSI. Apache 2.0 ajoute une concession de brevet explicite, que certaines équipes juridiques préfèrent. Chaque outil ci-dessous porte l'une des deux.

Sortie auto-hébergeable. L'intérêt des documents ouverts est que rien ne dépend des serveurs d'un fournisseur. Ces outils écrivent des fichiers statiques : du Markdown que vous commettez, une seule page HTML, ou un dossier de HTML/CSS/JS. Vous l'hébergez sur GitHub Pages, S3, ou un simple serveur Nginx, et cela continue de fonctionner que le projet derrière l'outil soit maintenu ou non.

Maintenance et communauté. Le code source disponible n'aide que si le code est vivant. Les étoiles, les commits récents et les problèmes ouverts vous indiquent si un fork serait viable si vous en aviez besoin un jour. Quelques outils ici sont archivés mais fonctionnent toujours ; je le préciserai.

Pour l'angle sans coût, à travers les options open et freemium, la liste des outils de documentation API gratuits est la pièce complémentaire. Maintenant, les outils.

Redocly CLI

Redocly CLI est le moyen le plus rapide de transformer une spécification en une référence HTML soignée et autonome. Il est sous licence MIT et en open core : le CLI et le moteur de rendu Redoc sous-jacent sont open source sur GitHub, tandis que certaines fonctionnalités de portail hébergé se trouvent dans le produit payant de Redocly. La commande build-docs fait entièrement partie de la moitié ouverte.

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

Cela écrit un fichier HTML construit sur Redoc. Ouvrez-le localement, déposez-le sur n'importe quel hôte statique, ou attachez-le à une release. Rien ne communique avec l'extérieur, et vous pouvez l'exécuter hors ligne une fois le package mis en cache.

Idéal pour : une référence API propre sur une seule page à partir d'une seule commande, sous licence MIT et auto-hébergée. Limites honnêtes : la sortie est une seule page, c'est donc une référence plutôt qu'un portail multi-pages, et la thématisation plus riche se trouve dans le niveau payant. Si vous comparez les moteurs de rendu entre eux, la comparaison des alternatives Redocly explique où se situe la limite de l'open source.

Widdershins

Widdershins est un pur convertisseur sous licence MIT. Il lit OpenAPI 3, Swagger 2 ou AsyncAPI et émet du Markdown ; c'est tout son travail. Parce que la sortie est du Markdown simple, vous le possédez complètement : commitez-le, comparez-le dans une pull request, ou alimentez-en n'importe quel site statique que vous utilisez déjà.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

Le Markdown qu'il écrit est compatible avec Slate, ce qui le marie parfaitement avec les générateurs de sites plus tard dans cette liste. Drapeaux utiles : --omitHeader supprime le front-matter, et --language_tabs sélectionne les langages des exemples de code.

Idéal pour : obtenir le contenu de la spécification en Markdown versionnable sans aucune dépendance. Limites honnêtes : le Markdown est tout ce que vous obtenez. Il n'y a pas de style et pas de site rendu, donc Widdershins est la moitié d'un pipeline ; autre chose transforme le Markdown en pages.

OpenAPI Generator

OpenAPI Generator est sous licence Apache 2.0 et géré par la communauté, fork d'Swagger Codegen en 2018. Il est surtout connu pour les SDK clients, mais il fournit également des générateurs de documentation : le générateur markdown écrit un dossier de Markdown, et html2 écrit une seule page HTML autonome.

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/

La licence Apache 2.0 et sa concession de brevet facilitent son approbation par les équipes juridiques prudentes, et le projet est l'un des plus activement maintenus dans cet espace.

Idéal pour : réutiliser un seul outil pour les SDK et les documents, sous une licence permissive avec un fort soutien communautaire. Limites honnêtes : le wrapper npm télécharge toujours un jar Java lors de la première exécution, ce n'est donc pas un binaire unique, et la sortie templatisée est simple. Si vous n'avez besoin que de documents, des convertisseurs plus légers existent.

Swagger Codegen

Swagger Codegen est le générateur original basé sur des modèles de l'équipe Swagger, sous licence Apache 2.0. Il est antérieur au fork OpenAPI Generator et est toujours maintenu par SmartBear. Pour la documentation, il offre deux chemins : html pour une référence statique sur une seule page et dynamic-html pour un petit site interactif.

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/

Les deux projets partagent un ADN et de nombreuses options, donc si votre équipe a déjà standardisé la chaîne d'outils Swagger, cela vous permet de rester à l'intérieur de celle-ci.

Idéal pour : les équipes déjà investies dans l'écosystème Swagger qui veulent de la documentation à partir du même outil Apache 2.0 qui génère leurs stubs. Limites honnêtes : il est basé sur Java comme OpenAPI Generator, et le développement est plus lent que le fork communautaire. Pour la plupart des nouvelles configurations, OpenAPI Generator est le choix le plus actif ; Swagger Codegen gagne sur la continuité.

Docusaurus avec le plugin OpenAPI

Si une seule page HTML ne suffit pas et que vous voulez un vrai site de documentation versionné, Docusaurus est l'ancre open source. Il est sous licence MIT, développé par Meta, et l'un des générateurs de sites statiques les plus utilisés sur le web. Seul, il rend le Markdown et le MDX ; le plugin docusaurus-openapi-docs, également sous licence MIT et maintenu par Palo Alto Networks, ajoute la génération de spécifications vers la documentation.

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

Après avoir configuré le plugin avec le chemin de votre spécification, gen-api-docs convertit le fichier OpenAPI en pages MDX qui s'affichent à l'intérieur du site Docusaurus, complètes avec un panneau « essayer » et une navigation latérale.

Idéal pour : un portail de documentation complet et auto-hébergé avec gestion de versions, recherche et guides rédigés à la main à côté de la référence générée. Limites honnêtes : c'est la configuration la plus lourde ici. Vous mettez en place un site React et une étape de build, c'est donc excessif si tout ce dont vous avez besoin est une page de référence. Pour cela, Redocly CLI est le chemin le plus court.

Slate

Slate est la mise en page classique des documents API à trois colonnes : navigation à gauche, prose au milieu, exemples de code à droite, le tout rendu comme un site statique. Il est sous licence Apache 2.0 et alimenté par Middleman, il nécessite donc une chaîne d'outils Ruby. Contrairement aux convertisseurs ci-dessus, Slate ne lit pas directement OpenAPI ; vous écrivez du Markdown, et Slate le rend.

# after cloning your Slate fork and running bundle install
bundle exec middleman build

Cela écrit un site statique complet dans un dossier build/ que vous hébergez n'importe où. C'est là que Widdershins prend tout son sens : convertissez votre spécification en Markdown, puis laissez Slate la rendre dans cette mise en page reconnaissable.

Idéal pour : des documents narratifs, faits à la main, où vous voulez un contrôle éditorial sur la structure et la prose, sur un site statique entièrement auto-hébergé. Limites honnêtes : le dépôt original est archivé (le mainteneur s'est retiré), bien qu'il se compile toujours et que les forks soient actifs, et la dépendance Ruby est plus lourde qu'un npx en une ligne. Si vos documents se régénèrent directement à partir d'une spécification, un convertisseur est plus léger.

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

Les outils ci-dessus sont tous open source, et chacun couvre une partie : convertir, rendre, ou héberger un fichier statique. Le vide qu'ils laissent est un projet en direct. Si votre API n'est pas un fichier YAML isolé mais un projet maintenu avec des endpoints, des schémas et des exemples, vous finissez par chaîner un convertisseur, un moteur de rendu et un hôte à la main et par les maintenir tous les trois synchronisés.

C'est le vide que le binaire apidog-cli comble. Pour être direct sur la licence : Apidog n'est pas open source. C'est une plateforme commerciale freemium avec un niveau gratuit, et le CLI communique avec un projet hébergé plutôt qu'avec une spécification locale. Je l'inclus ici uniquement pour que la comparaison soit honnête sur ce que les outils open source couvrent et ne couvrent pas, et non comme une option open source.

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

Une exportation transforme le projet en Markdown ou HTML sans pipeline de build, et apidog doc et apidog docs-site gèrent les ressources de documentation à partir d'un script. La sortie est au format JSON structuré, elle s'intègre donc proprement dans un CI ou un agent. Le guide complet d'Apidog CLI détaille l'authentification et chaque groupe de commandes. Si le workflow d'exportation Markdown est ce que vous recherchez, l'article sur le générateur de documents API avec exportation Markdown approfondit le sujet.

Où se situe la limite : les outils open source vous donnent un code que vous possédez, des fichiers que vous auto-hébergez, et aucune dépendance vis-à-vis d'un fournisseur. Apidog vous offre une voie intégrée d'un projet maintenu vers des documents partageables, au prix d'être un produit freemium hébergé. Choisissez en fonction de si votre source de vérité est une spécification statique ou un projet en direct.

Comment choisir

Faites correspondre la licence et la sortie à ce que votre équipe a besoin de posséder.

En bref : pour une spécification nue et une référence HTML partageable, utilisez Redocly CLI. Pour le Markdown que vous gérez en version, Widdershins. Si vous générez déjà des SDK, OpenAPI Generator fait aussi de la documentation, et Swagger Codegen vous couvre si vous êtes standardisé sur Swagger. Lorsque vous voulez un véritable portail avec versioning et guides, Docusaurus plus le plugin OpenAPI est l'ancre open source, et Slate est le choix pour des documents écrits à la main et contrôlés éditorialement. Chacun d'eux est disponible en code source et auto-hébergeable, donc rien de ce que vous livrez ne dépend de la pérennité d'un fournisseur. Pour une vue plus large sans coût, le récapitulatif des outils de documentation API gratuits rassemble les options open source et freemium.

Conclusion

Le choix d'un CLI de documentation open source se résume à la licence, à la sortie et à l'endroit où résident vos documents. MIT et Apache 2.0 vous permettent tous deux d'utiliser, de modifier et d'auto-héberger sans coût de licence, alors choisissez l'outil le plus petit qui produit la sortie dont vous avez besoin : Redocly CLI pour une page, Widdershins pour du Markdown, OpenAPI Generator ou Swagger Codegen pour la documentation à côté de vos SDKs, Docusaurus pour un portail, Slate pour des pages faites à la main.

Si votre API réside dans un projet maintenu plutôt que dans un fichier isolé, et que vous préférez exporter la documentation plutôt que d'enchaîner trois outils, Téléchargez Apidog et essayez apidog export sur un projet. Il s'intègre à un job de CI afin que votre documentation soit reconstruite à chaque modification de l'API, mais soyez conscient qu'il s'agit d'une plateforme freemium et non d'un binaire open source.