DEV Community

Cover image for Meilleurs outils CLI légers pour la conception d'API
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Meilleurs outils CLI légers pour la conception d'API

La plupart des outils de conception d’API sont plus lourds que nécessaire. Pour vérifier une convention de nommage, regrouper une spécification répartie sur plusieurs fichiers ou détecter un renommage de champ cassant, vous devriez pouvoir lancer une commande — sans application de bureau, service à configurer ni compte à créer.

Essayez Apidog dès aujourd'hui

Cette sélection se concentre sur des outils CLI rapides à installer, simples à lancer et adaptés à la CI. Chaque outil répond à une tâche précise : lint, bundling, génération de code, détection de changements cassants ou conception de points de terminaison. Pour replacer ces étapes dans un workflow complet, consultez d’abord ce guide sur comment concevoir une API.

Tous les outils présentés s’appuient sur la spécification OpenAPI. Une spécification créée ou exportée par un outil peut donc passer directement à l’étape suivante du pipeline.

Qu’est-ce qui rend un outil CLI léger pour la conception d’API ?

Un outil est léger lorsqu’il réduit le frottement entre votre spécification et un résultat exploitable.

Critères pratiques :

  1. Installation et démarrage rapides : un binaire autonome ou une commande npx est préférable à un service ou à un runtime lourd.
  2. Résultat utile sans configuration initiale : vous devez pouvoir pointer l’outil vers openapi.yaml et obtenir immédiatement un diagnostic.
  3. Exécutable en script et en CI : code de sortie clair, sortie lisible ou structurée, aucune interface graphique requise.

Les outils suivants sont classés approximativement du plus léger au plus complet.

Redocly CLI : lint et bundle sans installation globale

Redocly CLI est un bon point de départ si vous voulez éviter toute installation globale. Utilisez npx pour lancer le lint ou produire une spécification OpenAPI unique à partir de plusieurs fichiers.

npx @redocly/cli@latest lint openapi.yaml
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

La commande bundle résout les références $ref et fusionne une spécification découpée en plusieurs fichiers dans un seul document. C’est utile lorsque votre dépôt structure les ressources ainsi :

openapi/
├── openapi.yaml
├── paths/
│   ├── users.yaml
│   └── orders.yaml
└── schemas/
    ├── User.yaml
    └── Order.yaml
Enter fullscreen mode Exit fullscreen mode

Vous pouvez ensuite fournir dist/openapi.yaml à un générateur de SDK, à une documentation ou à un serveur mock.

Cette organisation rend aussi les revues Git plus lisibles et limite les conflits de fusion, en particulier dans un flux de travail de conception d’API natif Git.

Idéal pour : bundler des spécifications multi-fichiers et lancer un lint rapide sans installation globale.

Limite : les règles par défaut sont moins complètes qu’un guide de style personnalisé. Utilisez souvent Redocly pour le bundling et Spectral pour les règles d’équipe.

Spectral : rendre votre guide de style exécutable

Spectral est un linter open source pour OpenAPI, AsyncAPI et Arazzo. Il lit un ensemble de règles YAML, JSON ou JavaScript et les applique à votre spécification.

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

Sans fichier de règles, Spectral applique son jeu de règles OpenAPI intégré. Vous pouvez ensuite ajouter un fichier .spectral.yaml dans votre dépôt pour imposer les conventions de l’équipe.

Exemple minimal :

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

  kebab-case-paths:
    description: Les segments de chemin doivent utiliser le kebab-case.
    given: $.paths[*]~
    then:
      function: casing
      functionOptions:
        type: kebab
Enter fullscreen mode Exit fullscreen mode

Exécutez ensuite le lint dans votre CI :

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Avec cette approche, votre guide de style ne reste pas un document à consulter : il devient une vérification bloquante. C’est une application concrète des principes de conception d’API.

Idéal pour : appliquer des conventions de nommage, des schémas d’erreur partagés et des règles de documentation.

Limite : Spectral vérifie une version de spécification à la fois. Il ne compare pas deux versions pour détecter les ruptures de compatibilité.

oasdiff : bloquer les changements cassants

Un linter peut signaler une spécification mal structurée, mais il ne sait pas forcément qu’un champ supprimé cassera les clients existants. oasdiff compare deux versions OpenAPI pour identifier ces changements.

Installez-le avec Go :

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

Comparez ensuite l’ancienne et la nouvelle version :

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

Commandes utiles :

# Affiche uniquement les changements cassants
oasdiff breaking old-openapi.yaml new-openapi.yaml

# Produit un résumé lisible des changements
oasdiff changelog old-openapi.yaml new-openapi.yaml

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

Ajoutez oasdiff breaking à votre pipeline de pull request :

- name: Vérifier les changements cassants
  run: oasdiff breaking main-openapi.yaml openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Un changement incompatible devient alors une build en échec au lieu d’un incident en production.

Idéal pour : protéger les consommateurs d’API contre les changements incompatibles avec une configuration minimale.

Limite : oasdiff compare des spécifications ; votre contrat OpenAPI doit donc rester aligné sur l’API réellement déployée. Il ne remplace pas un linter de style.

Optic : lint et diff dans une CLI, avec une réserve

Optic combine lint et comparaison de spécifications dans une seule CLI.

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é en janvier 2026 et le projet n’est plus maintenu. Le code source sous licence MIT reste utilisable, mais il ne recevra plus de nouvelles règles ni de correctifs.

Pour un nouveau pipeline, privilégiez oasdiff pour la détection des changements cassants. Gardez néanmoins Optic en tête si vous le rencontrez dans une CI existante.

Idéal pour : les équipes qui utilisent déjà Optic et souhaitent conserver un outil unique pour le lint et le diff.

Limite : projet archivé depuis début 2026 ; prévoyez une migration.

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

openapi-generator transforme une spécification OpenAPI en SDK clients, stubs de serveur et documentation. C’est l’outil le plus lourd de cette liste car il s’appuie sur la JVM, mais son wrapper CLI simplifie son utilisation.

npm install -g @openapitools/openapi-generator-cli
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 stack :

# 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

# Stub de serveur Java
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server
Enter fullscreen mode Exit fullscreen mode

Exécutez cette génération à chaque modification de contrat pour empêcher les SDK de dériver de la spécification.

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

Ce workflow — traiter OpenAPI comme source de vérité et générer les artefacts dérivés — est au cœur du développement d’API axé sur la conception.

Idéal pour : maintenir SDK, stubs et documentation synchronisés avec le contrat.

Limite : nécessite un JDK 11 ou plus récent. Le code généré est souvent un point de départ à adapter selon le langage et le générateur choisis.

Apidog CLI : concevoir des points de terminaison et des schémas depuis le terminal

Les outils précédents vérifient, comparent ou transforment une spécification existante. Apidog intervient avant cela : sa CLI permet de gérer les points de terminaison et les schémas, puis d’exporter le résultat au format OpenAPI.

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

Les groupes de commandes disponibles incluent notamment :

endpoint
schema
security-scheme
folder
mock
import
export
Enter fullscreen mode Exit fullscreen mode

Vous pouvez ainsi intégrer la conception dans un workflow scriptable, puis envoyer la spécification exportée vers Spectral, Redocly, oasdiff ou openapi-generator.

La sortie JSON structurée et les champs agentHints.nextSteps facilitent l’enchaînement avec d’autres scripts. Consultez le guide complet d’Apidog CLI pour les commandes disponibles.

Apidog ne remplace pas un linter OpenAPI : utilisez Spectral ou Redocly pour appliquer votre guide de style. Apidog n’est pas non plus open source ; il s’agit d’un produit commercial avec un niveau gratuit.

Idéal pour : concevoir des points de terminaison et des schémas dans un espace unique, puis exporter un contrat OpenAPI.

Limite : ce n’est pas un linter et ce n’est pas open source ; il complète les outils de validation et de CI.

Comment choisir

Dans la pratique, utilisez deux ou trois outils plutôt qu’un seul.

Outil Idéal pour Installation Open source ? Remarques
Redocly CLI Bundling et lint rapide npx @redocly/cli@latest Oui, MIT Aucun install global ; adapté aux spécifications multi-fichiers
Spectral Linting de guide de style npm i -g @stoplight/spectral-cli Oui, Apache-2.0 Règles personnalisées versionnées dans le dépôt
oasdiff Détection des changements cassants go install github.com/oasdiff/oasdiff@latest Oui, Apache-2.0 Binaire Go unique ; maintenu
Optic Lint et diff combinés npm i -g @useoptic/optic Oui, MIT Dépôt archivé en janvier 2026
openapi-generator Génération de SDK, stubs et docs npm i -g @openapitools/openapi-generator-cli Oui, Apache-2.0 Nécessite un JDK 11+
Apidog CLI Conception et export OpenAPI npm i -g apidog-cli Non, niveau gratuit Conçoit et exporte ; ne lint pas

Pipeline minimal recommandé

Voici un pipeline simple et complémentaire :

  1. Concevez les points de terminaison et les schémas avec Apidog CLI, puis exportez OpenAPI.
  2. Appliquez les conventions de votre équipe avec Spectral.
  3. Regroupez les fichiers OpenAPI avec Redocly.
  4. Comparez le contrat avec la version de référence via oasdiff.
  5. Générez les SDK nécessaires avec openapi-generator.

Exemple de script :

#!/usr/bin/env bash
set -euo pipefail

# Exporter ou récupérer la spécification
apidog export --format openapi -o openapi.yaml

# Appliquer le guide de style
spectral lint openapi.yaml

# Produire un document OpenAPI unique
npx @redocly/cli@latest bundle openapi.yaml -o dist/openapi.yaml

# Bloquer les incompatibilités avec la version de référence
oasdiff breaking main-openapi.yaml dist/openapi.yaml

# Générer un client TypeScript
openapi-generator-cli generate \
  -i dist/openapi.yaml \
  -g typescript-axios \
  -o ./packages/api-client
Enter fullscreen mode Exit fullscreen mode

Pour explorer d’autres outils au-delà de la ligne de commande, consultez ce guide des alternatives à Swagger pour la conception et les tests d’API, ainsi que les bases de la conception d’API REST.

En résumé

Une boîte à outils CLI efficace pour la conception d’API peut rester très simple :

  • Redocly CLI pour regrouper et vérifier rapidement les spécifications ;
  • Spectral pour appliquer le guide de style ;
  • oasdiff pour bloquer les changements cassants ;
  • openapi-generator pour produire des clients et des stubs ;
  • Optic comme outil hérité à identifier dans les pipelines existants ;
  • Apidog CLI pour concevoir et exporter une spécification OpenAPI avant les validations.

L’objectif est d’exécuter les mêmes commandes localement et dans la CI à chaque push, sans dépendre d’une interface graphique.

Si vous préférez concevoir vos points de terminaison et schémas dans un espace intégré avant d’exporter OpenAPI, téléchargez Apidog et essayez apidog-cli.

Top comments (0)