DEV Community

Cover image for Outils CLI Open Source Gratuits pour la Conception d'API
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Outils CLI Open Source Gratuits pour la Conception d'API

La conception d’une API commence dans le fichier de spécification, bien avant l’expédition du code. Une règle de style oubliée, un changement majeur non détecté ou un schéma différent de la version livrée la semaine précédente coûtent bien plus cher à corriger après coup. Les outils en ligne de commande détectent ces problèmes à la source et les exécutent dans votre CI, sans dépendre d’une interface graphique.

Essayez Apidog dès aujourd’hui

Cette chaîne d’outils couvre la partie open source du cycle de conception API. Chaque outil présenté est sous licence permissive, gratuit à utiliser et peut être auto-hébergé ou épinglé à une version précise. C’est particulièrement utile lorsque votre contrat OpenAPI vit dans Git et que vous voulez obtenir le même résultat sur chaque poste de développement et dans chaque pipeline. Pour le contexte global, consultez notre guide sur comment concevoir une API.

Vous allez utiliser six outils :

  1. un linter de règles de style ;
  2. une alternative Go rapide, compatible avec les règles Spectral ;
  3. un bundler qui valide aussi la spécification ;
  4. un générateur de SDK, stubs et documentation ;
  5. deux outils de détection des changements majeurs.

Tous s’appuient sur la spécification OpenAPI. Une spécification validée par un outil peut donc passer directement à l’étape suivante.

Note sur Apidog : Apidog est mentionné comme outil complémentaire, mais ce n’est pas un projet open source et il ne remplace pas un linter OpenAPI. Les outils listés ci-dessous constituent la chaîne de validation open source.

Qu’est-ce qu’un outil CLI open source pour la conception d’API ?

Pour cette liste, un outil doit répondre à trois critères.

1. Une licence réellement open source

L’outil doit disposer d’une licence lisible et exploitable, par exemple MIT ou Apache-2.0. Vous devez pouvoir l’utiliser dans un projet commercial sans frais de licence ou limite de postes.

2. Un contrôle local et versionné

Vous devez pouvoir :

  • épingler une version précise ;
  • exécuter l’outil hors ligne ;
  • l’intégrer dans une image Docker ou un exécuteur CI isolé ;
  • éviter toute dépendance à un compte ou à un service externe pour la tâche principale.

3. Une maintenance vérifiable

Vérifiez avant d’adopter un outil :

  • l’activité récente du dépôt ;
  • les réponses aux tickets ;
  • la présence d’un changelog ;
  • l’état du projet : actif, en maintenance ou archivé.

Les outils ci-dessous sont présentés avec ces critères en tête.

Spectral : appliquer votre guide de style OpenAPI

Spectral, par Stoplight, est le linter OpenAPI de référence. Sous licence Apache-2.0, il applique un ensemble de règles à des documents OpenAPI 3.x, OpenAPI 2.0, AsyncAPI et Arazzo.

Installez-le puis lancez une première validation :

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Par défaut, Spectral fournit des règles oas qui signalent notamment :

  • les descriptions manquantes ;
  • les exemples invalides ;
  • certains problèmes structurels ;
  • des incohérences dans la spécification.

Sa valeur principale est la création de règles d’équipe versionnées dans Git.

Créez par exemple un fichier .spectral.yaml :

extends:
  - spectral:oas

rules:
  operation-id-required:
    description: Chaque opération doit définir un operationId.
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy
Enter fullscreen mode Exit fullscreen mode

Exécutez ensuite le linter avec ce fichier à la racine du dépôt :

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Utilisez Spectral pour imposer, par exemple :

  • un operationId sur chaque opération ;
  • un format de nommage pour les chemins ;
  • une structure commune pour les réponses d’erreur ;
  • des descriptions obligatoires ;
  • des conventions sur les en-têtes ou paramètres.

Idéal pour : transformer un guide de style API en vérifications exécutables.

Limite : Spectral analyse une version de spécification à la fois. Associez-le à un outil de diff pour détecter les changements majeurs.

vacuum : exécuter les règles Spectral plus rapidement

Si Spectral est la référence fonctionnelle, vacuum privilégie la vitesse. Écrit en Go et sous licence MIT, il est compatible avec les ensembles de règles Spectral.

Installez-le et analysez votre spécification :

brew install --cask daveshanley/vacuum/vacuum
vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

L’option -d affiche les diagnostics détaillés, règle par règle.

Vous pouvez réutiliser le même fichier .spectral.yaml que pour Spectral. Cela facilite une migration progressive : gardez vos règles existantes et remplacez seulement l’exécuteur dans les workflows où le temps d’exécution est critique.

Exemple dans un hook de pré-commit ou une CI :

vacuum lint -d openapi.yaml
Enter fullscreen mode Exit fullscreen mode

vacuum peut aussi générer des rapports HTML et de la documentation à partir de la spécification.

Idéal pour : valider rapidement de grandes spécifications avec des règles Spectral existantes.

Limite : l’écosystème de règles reste fortement centré sur Spectral. Spectral demeure souvent le meilleur point de départ pour écrire et comprendre les règles.

Redocly CLI : valider et regrouper une spécification multi-fichiers

Redocly CLI, sous licence MIT, combine validation et regroupement. Sa commande bundle est particulièrement utile lorsque votre contrat OpenAPI est réparti dans plusieurs fichiers via $ref.

Installation :

npm install -g @redocly/cli
Enter fullscreen mode Exit fullscreen mode

Validation :

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Regroupement dans un artefact unique :

redocly bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Une structure de dépôt multi-fichiers peut ressembler à ceci :

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── components/
    ├── schemas/
    │   └── user.yaml
    └── responses/
        └── errors.yaml
Enter fullscreen mode Exit fullscreen mode

Ce découpage rend les revues de code plus lisibles et limite les conflits de fusion. C’est particulièrement utile dans un flux de travail de conception d’API natif de Git.

Ajoutez ensuite l’artefact regroupé à votre pipeline :

redocly lint openapi/openapi.yaml
redocly bundle openapi/openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Les autres outils de la chaîne peuvent alors consommer dist/openapi.yaml.

Idéal pour : les spécifications multi-fichiers utilisant $ref.

Limite : les règles par défaut sont généralement moins poussées qu’un jeu de règles Spectral personnalisé. Beaucoup d’équipes utilisent Redocly pour le bundling et Spectral ou vacuum pour le style.

openapi-generator : générer clients, stubs et documentation

Une spécification n’est utile que si les autres équipes peuvent construire dessus. openapi-generator, sous licence Apache-2.0, génère des SDK clients, stubs serveur et documentation dans de nombreux langages.

Installez le CLI :

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

Générez un client TypeScript basé sur Axios :

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Remplacez typescript-axios par le générateur adapté à votre environnement :

# Client Go
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go

# Client Python
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python

# Client Java
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
Enter fullscreen mode Exit fullscreen mode

Ajoutez cette génération à la CI après la validation et le bundling :

redocly bundle openapi.yaml -o dist/openapi.yaml

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./generated/client
Enter fullscreen mode Exit fullscreen mode

Cette approche maintient les clients alignés avec le contrat. Elle s’inscrit dans une pratique schema-first et contractuelle, détaillée dans les principes de conception d’API.

Idéal pour : générer SDK, stubs et documentation depuis une source de vérité OpenAPI.

Limite : l’outil nécessite un JDK 11 ou supérieur. Le code généré est un point de départ à vérifier et à adapter selon le générateur cible.

oasdiff : bloquer les changements majeurs avant la mise en production

Un linter peut confirmer que votre spécification est valide. Il ne peut pas déterminer qu’un renommage de champ casse tous les clients existants.

oasdiff, sous licence Apache-2.0 et écrit en Go, compare deux versions d’une spécification OpenAPI et identifie les changements incompatibles.

Installez-le :

go install github.com/oasdiff/oasdiff@latest
Enter fullscreen mode Exit fullscreen mode

Comparez une ancienne et une nouvelle version :

oasdiff breaking old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Les commandes principales sont :

# Afficher uniquement les changements incompatibles
oasdiff breaking old-openapi.yaml new-openapi.yaml

# Générer un changelog lisible
oasdiff changelog old-openapi.yaml new-openapi.yaml

# Obtenir le diff complet
oasdiff diff old-openapi.yaml new-openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Dans une pull request, comparez la branche courante à votre référence :

oasdiff breaking main-openapi.yaml dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Si la commande retourne un changement majeur, faites échouer le job CI. Vous transformez ainsi une régression de contrat en échec de build plutôt qu’en incident côté client.

Idéal pour : empêcher les changements incompatibles dans les pull requests.

Limite : oasdiff compare uniquement les spécifications. Il dépend donc de la qualité et de l’actualité de votre contrat OpenAPI. Utilisez-le avec Spectral ou vacuum pour les règles de style.

Optic : diff et lint dans une seule CLI, avec une mise en garde

Optic, sous licence MIT, combinait validation et comparaison OpenAPI. Il peut comparer deux versions pour identifier les changements majeurs tout en appliquant des règles de style. Il pouvait également générer une spécification à partir de trafic de test observé.

Installation et comparaison :

npm install -g @useoptic/optic
optic diff old-openapi.yaml new-openapi.yaml --check
Enter fullscreen mode Exit fullscreen mode

Cependant, le dépôt public d’Optic a été archivé début 2026 et le projet n’est plus activement maintenu. Le code sous licence MIT reste disponible, mais vous ne devez pas compter sur de nouvelles règles ou des correctifs futurs.

Pour un nouveau pipeline, préférez oasdiff pour les changements majeurs. Gardez Optic en tête si vous le rencontrez dans un pipeline existant et prévoyez une migration.

Idéal pour : les équipes ayant déjà investi dans Optic.

Limite : projet archivé début 2026 ; considérez-le comme une dépendance héritée.

Où Apidog s’intègre, et où il ne s’intègre pas

Apidog n’est pas open source et ne valide pas votre OpenAPI ni vos règles de style. Pour cela, utilisez Spectral, vacuum ou Redocly CLI.

En revanche, Apidog propose une approche intégrée pour concevoir les endpoints et schémas, puis exporter la spécification OpenAPI afin de l’envoyer dans votre chaîne de validation open source.

Installez le CLI :

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Connectez-vous puis exportez votre contrat :

apidog login --with-token <YOUR_TOKEN>
apidog endpoint list
apidog export --format openapi -o openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Vous pouvez ensuite transmettre le fichier exporté aux autres outils :

spectral lint openapi.yaml

redocly bundle openapi.yaml -o dist/openapi.yaml

oasdiff breaking previous-openapi.yaml dist/openapi.yaml

openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Le CLI propose des groupes de commandes pour endpoint, schema, mock et import/export. Consultez le guide complet du CLI Apidog pour le détail des commandes.

Apidog est donc un complément commercial pour la conception et l’export, pas un remplacement pour un linter ni un outil open source.

Comment choisir

La plupart des équipes combinent plusieurs outils.

Outil Idéal pour Installation Open source ? Notes
Spectral Validation d’un guide de style npm i -g @stoplight/spectral-cli Oui, Apache-2.0 Linter de référence ; règles personnalisables
vacuum Validation rapide à grande échelle brew install --cask daveshanley/vacuum/vacuum Oui, MIT Exécute les règles Spectral ; binaire Go
Redocly CLI Bundling et validation npm i -g @redocly/cli Oui, MIT Adapté aux spécifications multi-fichiers avec $ref
openapi-generator Génération de SDK, stubs et documentation npm i -g @openapitools/openapi-generator-cli Oui, Apache-2.0 Nécessite JDK 11+
oasdiff Détection des changements majeurs go install github.com/oasdiff/oasdiff@latest Oui, Apache-2.0 À exécuter dans les vérifications de PR
Optic Validation et diff dans un outil npm i -g @useoptic/optic Oui, MIT Dépôt archivé début 2026
Apidog CLI Conception intégrée et export OpenAPI npm i -g apidog-cli Non, niveau gratuit Ne remplace pas un linter

Une pile CI pratique

Voici une séquence simple et actionnable :

# 1. Vérifier les règles de style
spectral lint openapi.yaml

# 2. Produire un document OpenAPI unique
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. Refuser les changements incompatibles
oasdiff breaking previous-openapi.yaml dist/openapi.yaml

# 4. Générer le SDK client
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./generated/client
Enter fullscreen mode Exit fullscreen mode

Utilisez :

  • Spectral ou vacuum pour le style ;
  • Redocly CLI pour regrouper les fichiers ;
  • oasdiff pour bloquer les changements majeurs ;
  • openapi-generator pour produire les clients.

Si vous préférez concevoir et exporter depuis une plateforme intégrée, utilisez-la en amont de cette chaîne. Pour aller plus loin, consultez les alternatives à Swagger pour la conception et les tests d’API ainsi que ce guide sur comment concevoir des API REST.

Conclusion

La chaîne CLI open source pour la conception d’API est mature :

  • Spectral et vacuum valident les règles ;
  • Redocly regroupe les spécifications ;
  • openapi-generator produit les clients et artefacts ;
  • oasdiff protège le contrat contre les changements majeurs ;
  • Optic reste une option héritée à identifier dans les pipelines existants.

Ajoutez ces vérifications à votre CI pour contrôler le contrat API à chaque push, sans coût par poste et sans dépendance à un fournisseur.

Si vous souhaitez concevoir des endpoints et schémas dans un outil intégré avant d’exporter un OpenAPI propre vers ce pipeline, téléchargez Apidog et testez apidog-cli. Quel que soit votre flux, l’objectif reste le même : détecter les problèmes de conception dans le terminal avant qu’ils n’atteignent les utilisateurs.

Top comments (0)