Outils CLI Open Source Gratuits pour la Conception d'API

La conception d'API a lieu dans votre fichier de spécification bien avant l'expédition du code. Une règle de style oubliée, un changement majeur manqué, un schéma qui s'écarte de ce que vous avez livré la semaine dernière ; tout cela coûte plus cher à corriger après coup. La ligne de commande détecte ces problèmes là où ils commencent, et elle le fait en CI sans que personne n'ait à naviguer dans une interface utilisateur.

Cet article concerne la partie open-source de cette chaîne d'outils. Chaque outil présenté ici est disponible sous licence permissive, gratuit à utiliser sans coût de licence, et quelque chose que vous pouvez auto-héberger ou épingler à une version que vous contrôlez. C'est important lorsque la conception de votre API se trouve dans un dépôt Git et que vous souhaitez que les vérifications s'exécutent de la même manière sur chaque ordinateur portable et chaque pipeline. Si vous voulez avoir une vue d'ensemble de la façon dont tout cela s'assemble, commencez par notre guide sur comment concevoir une API, puis revenez ici pour choisir les CLI.

Vous obtiendrez six outils, chacun avec une commande d'installation réelle et la commande unique qui montre son fonctionnement : un linter pour les règles de style, une alternative rapide basée sur Go, un bundler qui valide également, un générateur de code et de documentation, et deux outils pour détecter les changements majeurs entre les versions de spécification. La spécification OpenAPI est le langage commun que tous ces outils parlent, de sorte qu'une spécification que vous validez avec un outil s'intègre proprement au suivant.

Une note honnête d'emblée. Apidog est présenté ici, mais il n'est pas open source ; c'est un produit commercial avec un niveau gratuit, et il ne valide pas votre spécification. Il est donc mentionné de manière pertinente, mais pas comme une entrée open source. Les outils ci-dessous constituent la véritable chaîne d'outils de conception open source.

Qu'est-ce qui rend un outil CLI open source pour la conception d'API

L'open source est une affirmation spécifique, pas une impression. Pour cette liste, un outil est qualifié lorsque trois conditions sont remplies.

Premièrement, la licence. Il doit s'agir d'une véritable licence permissive ou copyleft que vous pouvez lire ; MIT et Apache-2.0 sont les deux que vous verrez le plus souvent ici. C'est ce qui vous permet d'utiliser l'outil dans un projet commercial sans frais de licence ni nombre de postes.

Deuxièmement, l'auto-hébergement et le contrôle de version. Vous pouvez intégrer le binaire, épingler une version exacte et l'exécuter entièrement hors ligne dans un exécuteur CI isolé. Aucun outil ici ne contacte un serveur externe ou n'a besoin d'un compte pour accomplir sa tâche principale.

Troisièmement, la maintenance et la communauté. Un dépôt avec des commits récents, des problèmes ouverts qui reçoivent des réponses, et un journal des modifications public. Un projet abandonné peut toujours être sous licence MIT et rester un mauvais pari, c'est pourquoi je signale l'état de la maintenance là où cela compte.

Chaque outil ci-dessous est vérifié par rapport à ces trois critères. Lorsqu'un projet stagne, cela sera signalé.

Spectral : le linter de style OpenAPI flexible

Spectral de Stoplight est le linter open source de référence pour les descriptions d'API, sous licence Apache-2.0. Il lit un ensemble de règles (un fichier YAML, JSON ou JavaScript listant vos règles) et l'applique aux documents OpenAPI 3.x, OpenAPI 2.0, AsyncAPI et Arazzo. Si votre équipe dispose d'un guide de style API écrit, Spectral est la manière de le rendre exécutable.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Par défaut, il fournit un ensemble de règles oas qui signale les descriptions manquantes, les exemples non valides et les problèmes structurels. La vraie valeur réside dans les règles personnalisées : exiger un operationId sur chaque opération, un schéma partagé sur les réponses d'erreur, une convention de nommage sur les chemins. Ces règles vivent dans votre dépôt et s'exécutent de manière identique pour chaque contributeur.

Idéal pour : faire respecter un guide de style d'équipe sous forme de code. Limite honnête : Spectral vérifie une seule spécification ; il ne compare pas deux versions, alors associez-le à un outil de comparaison pour détecter les changements majeurs.

vacuum : le linter le plus rapide, compatible avec les règles Spectral

Si Spectral est la norme, vacuum est le choix de la vitesse. C'est un linter Go, sous licence MIT, 100% compatible avec les ensembles de règles Spectral. Vous pouvez donc le pointer vers le même ensemble de règles que vous avez déjà écrit et obtenir des résultats beaucoup plus rapidement sur de grandes spécifications, ce qui est exactement ce que vous voulez dans un hook de pré-commit ou une boucle CI serrée.

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml

L'indicateur -d vous donne une sortie détaillée par règle. vacuum fait également plus que la validation ; il génère des rapports HTML et de la documentation à partir de la même spécification. Parce que c'est un seul binaire compilé sans environnement d'exécution Node, il démarre rapidement et s'intègre proprement dans un conteneur.

Idéal pour : la validation rapide de grandes spécifications avec des ensembles de règles que vous possédez déjà. Limite honnête : l'écosystème et la documentation des ensembles de règles restent centrés sur Spectral, vous écrivez donc souvent des règles par rapport au modèle de Spectral et les exécutez via vacuum. C'est une fonctionnalité, mais cela signifie que Spectral est toujours la première chose à apprendre.

Redocly CLI : linter et bundler en un seul binaire

Redocly CLI est sous licence MIT et couvre une tâche légèrement différente. Il effectue la validation, mais son point fort est bundle : il prend une spécification divisée en plusieurs fichiers $ref (la manière sensée de maintenir une grande conception d'API) et la fusionne en un seul document pour les outils qui attendent un fichier unique. Il génère également des documents de référence d'API à partir du résultat du regroupement.

npm install -g @redocly/cli
redocly lint openapi.yaml
redocly bundle openapi.yaml -o dist/openapi.yaml

Diviser votre spécification en fichiers par ressource maintient les différences lisibles et les conflits de fusion faibles, ce qui est essentiel pour un flux de travail de conception d'API natif de Git. Le bundle de Redocly est l'étape qui transforme cette source multi-fichiers en l'artefact unique que votre CI, serveur de maquette ou site de documentation consomme.

Idéal pour : les projets de spécification multi-fichiers qui nécessitent un regroupement ainsi qu'un passage de validation. Limite honnête : ses règles de validation par défaut sont plus légères qu'un ensemble complet de règles Spectral personnalisées, de sorte que de nombreuses équipes utilisent Redocly pour le regroupement et Spectral ou vacuum pour une application approfondie du style.

openapi-generator : transformer la conception en clients, stubs et documentation

La conception n'est pas terminée tant que d'autres personnes ne peuvent pas s'appuyer dessus. openapi-generator est sous licence Apache-2.0 et génère des SDK clients, des stubs de serveur et de la documentation à partir d'une spécification OpenAPI dans des dizaines de langages. Traiter la spécification comme la source de vérité et générer le reste est au cœur d'une approche "schema-first", axée sur le contrat, que nous abordons dans les principes de conception d'API.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

Remplacez -g typescript-axios par go, python, java, kotlin, ou n'importe quel générateur parmi les nombreux pris en charge. Exécutez-le en CI à chaque changement de spécification et vos bibliothèques clientes ne s'écarteront jamais du contrat.

Idéal pour : maintenir le code et la documentation générés en phase avec la conception. Limite honnête : il nécessite un JDK pour fonctionner (JDK 11+), le code généré est un point de départ que vous personnaliserez souvent, et la qualité du générateur varie selon le langage cible. Vérifiez la sortie avant de la livrer.

oasdiff : détecter les changements majeurs avant qu'ils n'atteignent les clients

Un linter vous dit si une spécification est propre. Il ne peut pas vous dire que le renommage d'un champ vient de casser chaque client en production. oasdiff est l'outil Go sous licence Apache-2.0 qui comble cette lacune : donnez-lui deux versions d'une spécification et il rapporte la différence, et spécifiquement les changements majeurs.

go install github.com/oasdiff/oasdiff@latest
oasdiff breaking old-openapi.yaml new-openapi.yaml

La commande breaking ne révèle que les changements qui cassent les consommateurs existants ; changelog donne une liste lisible par l'homme de tout ce qui a changé, majeur ou non ; diff donne le delta complet lisible par machine. Intégrez oasdiff breaking dans une vérification de pull-request et un changement majeur deviendra une construction échouée au lieu d'un appel à 3 heures du matin.

Idéal pour : bloquer les changements majeurs en CI. Limite honnête : il compare les spécifications, donc il n'est aussi bon que votre discipline à maintenir la spécification à jour avec l'API réelle. Il ne valide pas le style ; utilisez-le avec Spectral ou vacuum.

Optic : diff et lint ensemble, avec une mise en garde sur la maintenance

Optic est sous licence MIT et fait quelque chose que les autres séparent : il valide et compare OpenAPI dans un seul outil, comparant deux versions pour signaler les changements majeurs tout en appliquant des règles de style. Il pourrait même générer une spécification à partir du trafic de test observé.

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check

Voici l'honnêteté qu'une liste open source vous doit : le dépôt public d'Optic a été archivé début 2026 et le projet n'est plus activement maintenu. La source MIT fonctionne toujours, vous pouvez donc l'intégrer, mais vous n'obtiendrez pas de nouvelles règles ni de correctifs de sécurité. Pour la détection des changements majeurs aujourd'hui, oasdiff est l'option maintenue ; Optic reste sur la liste parce que vous le rencontrerez encore dans les pipelines existants.

Idéal pour : les équipes qui y ont déjà investi, ou quiconque souhaite la validation et la comparaison dans une seule CLI. Limite honnête : plus maintenu à partir de début 2026 ; traitez-le comme un héritage et prévoyez un chemin de migration.

Où Apidog s'intègre (et où il ne s'intègre pas)

Apidog n'est pas open source, et il ne valide pas votre OpenAPI ni n'applique de règles de style ; Spectral, vacuum et Redocly sont vos linters, point final. Ce qu'Apidog offre est un compromis différent : au lieu d'assembler six binaires distincts, son niveau gratuit et le binaire apidog-cli vous offrent un endroit intégré pour concevoir des points de terminaison et des schémas de données, puis exporter le résultat en OpenAPI pour le réintégrer directement dans ces vérifications open source.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml

La CLI dispose de groupes de commandes pour endpoint, schema, mock, et import/export, vous permettant ainsi de script-er la conception d'API depuis le terminal et de transmettre la spécification exportée à openapi-generator ou oasdiff. Consultez le guide complet de l'CLI Apidog pour l'ensemble des commandes. La présentation honnête : Apidog est l'option commerciale intégrée qui fonctionne bien avec la chaîne d'outils open source, non pas un remplacement pour un linter et non pas un projet open source en soi.

Comment choisir

Adaptez l'outil à la tâche. La plupart des équipes utilisent deux ou trois de ces outils ensemble, pas un seul.

Une pile pratique : Spectral ou vacuum pour le style, Redocly pour le regroupement, oasdiff pour les changements majeurs, et openapi-generator pour produire les clients. Si la maintenance de tant d'outils est plus que ce que vous souhaitez gérer, une plateforme intégrée couvre la partie conception et exportation en un seul endroit. Pour un aperçu plus large du paysage des outils au-delà de la CLI, consultez notre guide sur les alternatives à Swagger pour la conception et les tests d'API et les fondamentaux sur comment concevoir des API REST.

Conclusion

La chaîne d'outils CLI open source pour la conception d'API est mature et gratuite à utiliser : Spectral et vacuum valident, Redocly regroupe, openapi-generator produit des clients, et oasdiff protège contre les changements majeurs, avec Optic comme option héritée à reconnaître. Intégrez-les à votre CI et votre contrat d'API sera vérifié à chaque push sans coût par poste et sans verrouillage fournisseur.

Si vous préférez concevoir des points de terminaison et des schémas dans un seul outil intégré et exporter un OpenAPI propre dans ce même pipeline, Téléchargez Apidog et essayez l'apidog-cli ; c'est le compagnon commercial de la pile open source, non pas un remplacement pour votre linter. Dans tous les cas, l'objectif est le même : détecter les problèmes de conception dans le terminal, avant qu'ils n'atteignent vos utilisateurs.