La meilleure alternative à Swagger CLI en 2026

Si vous êtes arrivé ici après avoir exécuté npm install -g @apidevtools/swagger-cli et remarqué les avertissements, voici la version courte : l'outil n'est plus maintenu. Le dépôt swagger-cli sur GitHub indique clairement qu'il est obsolète, citant « le fardeau de la maintenance lié aux efforts pour répondre aux attentes d'une vaste base d'utilisateurs avec peu ou pas de contributions ». Le README lui-même vous oriente vers Redocly CLI comme successeur.

Vous avez donc besoin d'un remplaçant. Il s'agit spécifiquement de l'outil de terminal swagger-cli, celui qui effectue les opérations validate et bundle. Si vous faites en fait référence à Swagger Editor, SwaggerHub ou à la suite de conception plus large, lisez plutôt 7 alternatives à Swagger qui testent également votre API.

Voyons ce que faisait swagger-cli, puis parcourons la liste honnête de ce qu'il faut utiliser maintenant.

Ce que swagger-cli faisait réellement

Il est important d'être précis, car le bon remplaçant dépend de ce que vous utilisiez.

swagger-cli avait exactement deux commandes :

# Valide une définition Swagger 2.0 / OpenAPI 3.0 par rapport au schéma et vérifie les $refs
swagger-cli validate openapi.yaml

# Suit les pointeurs $ref et combine une définition multi-fichiers en un seul fichier
swagger-cli bundle openapi.yaml -o bundled.json

La commande bundle disposait d'un petit ensemble d'options : -o/--outfile pour écrire dans un fichier, -t/--type pour choisir JSON ou YAML, -r/--dereference pour insérer entièrement chaque $ref, et -f/--format pour l'indentation.

C'est tout l'outil. Il validait la structure et regroupait les spécifications multi-fichiers. Il n'effectuait pas de linting avec des règles de style, ne générait pas de documentation, n'exécutait pas de tests et ne simulait rien. Si vous lisez des affirmations selon lesquelles swagger-cli « lintait » votre spécification, elles sont fausses ; il vérifiait uniquement votre définition par rapport au schéma OpenAPI et résolvait les références. Gardez cette portée à l'esprit, car certains remplaçants en font beaucoup plus, et vous ne le souhaitez peut-être pas.

La sélection

Trois outils couvrent presque toutes les raisons pour lesquelles vous utiliseriez swagger-cli, plus quelques spécialistes dignes de mention. Voici le bilan honnête.

Redocly CLI : le successeur officiel et l'échange 1:1 le plus proche

Redocly CLI (@redocly/cli, binaire redocly) est open source et est l'outil vers lequel le README de swagger-cli lui-même vous dirige. Redocly publie même un guide de migration depuis swagger-cli. Si votre objectif est un validateur et un bundler de terminal prêt à l'emploi, commencez ici.

Installez-le de la même manière que vous avez installé swagger-cli :

npm install -g @redocly/cli@latest
# ou exécuter sans installer
npx @redocly/cli@latest lint openapi.yaml

Le mappage est propre. La commande validate de swagger-cli devient redocly lint, qui vérifie votre spécification et applique des règles de style configurables. La commande bundle de swagger-cli devient redocly bundle :

# swagger-cli bundle -o output.json
redocly bundle openapi.yaml --output output.json

Voici le mappage des drapeaux de bundle côte à côte :

Une chose à savoir : redocly lint fait plus que la commande validate de swagger-cli par défaut. Il applique un ensemble de règles de guide de style, et pas seulement une vérification de schéma. Si vous voulez la simple validation structurelle que swagger-cli vous offrait, configurez un redocly.yaml avec uniquement la règle spec, puis exécutez redocly lint openapi.yaml. Ce comportement des règles est la force distinctive de Redocly plutôt qu'un inconvénient ; c'est pourquoi les équipes qui souhaitent une gouvernance native au terminal l'apprécient. Vous pouvez ajuster les ensembles de règles (minimal, recommended, recommended-strict, spec) ou écrire des règles personnalisées. Voir la meilleure configuration de linter OpenAPI pour voir comment cela s'intègre avec d'autres linters.

Redocly CLI va également au-delà des deux commandes de swagger-cli. Il peut split (diviser) une description unique en une structure multi-fichiers (l'inverse de bundle), join (joindre) plusieurs fichiers (expérimental), et construire des documents HTML Redoc autonomes :

redocly build-docs openapi.yaml -o docs.html

Ce qu'il ne fait pas : exécuter des tests d'API ou héberger un serveur de maquette. C'est un outil lint/bundle/docs axé sur le code, natif au terminal, et un excellent outil. Si c'est tout ce dont vous avez besoin, vous pouvez arrêter de lire et migrer dès aujourd'hui.

Apidog : lorsque vous voulez plus que valider et regrouper

Voici le recadrage honnête. swagger-cli était un script statique que vous exécutiez pour valider et regrouper. Mais pour la plupart des équipes, la validation et le regroupement sont des moyens d'atteindre une fin. Vous validez pour que la spécification soit correcte, vous regroupez pour qu'elle soit portable, puis vous la simulez, la testez et la documentez. swagger-cli déléguait ces étapes ultérieures à d'autres outils.

Apidog comble cette lacune. C'est une plateforme API tout-en-un : conception, maquette, test et documentation dans un seul espace de travail, avec une CLI qui gère l'importation, l'exportation et les exécutions de tests CI. Là où swagger-cli vous donnait un fichier, Apidog vous offre un espace de travail dynamique construit à partir de ce fichier.

Les deux commandes qui correspondent le plus directement à votre mémoire musculaire de swagger-cli sont import et export. Installez la CLI et authentifiez-vous d'abord :

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>

Vous obtenez le jeton depuis l'application ou le site web Apidog : avatar, puis Paramètres du compte, puis Jeton d'accès API. Il est stocké dans ~/.apidog/config.toml, ne l'affichez donc jamais et ne le commettez jamais.

L'importation est votre étape de validation. Elle ingère une définition dans un projet et résout les $ref multi-fichiers en ressources unifiées. Si le fichier est malformé, l'importation le révèle :

apidog import --project 123456 --format openapi --file ./openapi.json

L'importation accepte une longue liste de formats au-delà d'OpenAPI, y compris Postman, HAR, Insomnia, WSDL et JSON Schema, ce qui est pratique lorsque vos sources sont mélangées.

L'exportation est votre étape de regroupement, avec un bonus. Elle émet un seul fichier consolidé, et vous choisissez la version OpenAPI à la sortie. Cela en fait un regroupement plus une mise à niveau optionnelle de la spécification en une seule commande :

# Regrouper et mettre à niveau vers OpenAPI 3.1 en une seule fois
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

# Ou émettre des documents HTML autonomes
apidog export --project 123456 --format html --output ./docs.html

Pour l'intégration continue (CI), Apidog ajoute l'étape que swagger-cli n'a jamais eue : l'exécution de tests.

# Exécuter un scénario de test en CI avec plusieurs formats de rapport
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

# Ou exécuter entièrement hors ligne à partir d'un fichier de collection exporté
apidog run ./collection.apidog-cli.json

La CLI gère également directement les ressources du projet, y compris endpoint (point de terminaison), schema (schéma), mock (maquette), environment (environnement), branch (branche), test-suite (suite de tests) et test-report (rapport de test). Pour les détails de configuration et chaque option, consultez le guide complet de l'Apidog CLI et la documentation officielle de l'Apidog CLI.

Maintenant, les limites honnêtes, car l'adéquation est plus importante que le battage médiatique. La CLI d'Apidog valide la structure à l'importation, mais elle ne vous offre pas un linter de guide de style configurable, axé sur le code, avec des ensembles de règles personnalisés comme le fait lint de Redocly. Il n'y a pas de commande apidog lint, et vous ne pouvez pas créer de règles personnalisées de style Spectral via la CLI. Il n'y a pas non plus de split ou de join. Apidog est d'abord basé sur une interface graphique : la conception, la simulation, la création visuelle de tests et la documentation sont principalement créées dans l'application de bureau ou web, la CLI gérant l'importation, l'exportation, les exécutions de tests CI et la gestion des ressources d'un projet. Et Apidog est freemium, pas open source, c'est donc un modèle différent de Redocly CLI et Spectral.

Spectral : linting pur et personnalisable en CI

Si ce que vous attendiez réellement de swagger-cli était une validation stricte et opinionnée dans votre pipeline, le linter dédié est Spectral de Stoplight. Il est open source et conçu pour une seule tâche : appliquer un ensemble de règles personnalisables aux documents OpenAPI (et autres documents JSON/YAML).

Spectral excelle lorsque vous souhaitez appliquer un style de maison en tant que code, avec vos propres règles, dans chaque pull request. Il ne regroupe pas, ne génère pas de documentation et ne teste pas les points de terminaison ; il effectue du linting. Associez-le à un bundler et vous aurez reconstruit une version ciblée de ce que faisait swagger-cli, avec une véritable gouvernance. Notre guide sur le linting OpenAPI avec Spectral explique comment écrire des ensembles de règles, et la validation OpenAPI en CI couvre son intégration dans un pipeline.

En bref : openapi-generator et vacuum

Deux autres outils apparaissent, voici donc la version courte et précise. openapi-generator est un générateur de code et de client ; si votre raison de regrouper était d'alimenter un générateur, vous n'aurez peut-être pas besoin d'une étape de regroupement distincte du tout, car il consomme directement les spécifications. vacuum est un linter OpenAPI rapide et compatible avec Spectral, écrit en Go, un bon choix lorsque la vitesse de linting est importante dans les grands monorépos. Aucun des deux n'est un remplacement général de la validation et du regroupement à lui seul, mais tous deux répondent à des besoins spécifiques.

Tableau comparatif

Voici comment les options se comparent en fonction des capacités qui intéressent généralement les utilisateurs de swagger-cli.

La recommandation

Ce n'est pas une situation « tout est génial, choisissez votre préféré ». Deux voies claires couvrent presque tout le monde.

Choisissez Redocly CLI si vous voulez un remplacement prêt à l'emploi. C'est le successeur officiel, il est open source, et la migration est quasi mécanique : validate vers lint, bundle vers bundle, avec le mappage des options ci-dessus. Si votre flux de travail est véritablement juste « valider et regrouper depuis le terminal », et que vous souhaitez ajouter des règles de gouvernance plus tard sans changer d'outils, Redocly est le choix évident. Il vous maintient axé sur le code et natif au terminal, ce qui est exactement là où swagger-cli se situait.

Choisissez Apidog si la validation et le regroupement n'étaient que le début. La plupart des équipes ne valident pas une spécification pour le plaisir. Elles la valident, puis quelqu'un a besoin d'une maquette pour construire, quelqu'un d'autre écrit des tests, et quelqu'un gère la documentation. swagger-cli s'arrêtait à la première étape et vous obligeait à assembler le reste à partir de Spectral, d'un bundler, de Postman et de Newman. Apidog rassemble l'importation (validation), l'exportation (regroupement plus une mise à niveau de version OAS), la simulation, les tests et la documentation dans un seul espace de travail, avec une CLI pour les parties qui appartiennent à l'intégration continue (CI). Vous arrêtez de surveiller un script statique, désormais non maintenu, et amenez l'ensemble de la spécification dans un endroit où elle reste utile après avoir été regroupée.

Ce sont des paradigmes différents, pas des versions concurrentes de la même chose. Redocly CLI est le spécialiste léger, piloté par la configuration, que vous exécutez uniquement depuis le terminal. Apidog est la plateforme tout-en-un qui dispose d'une CLI performante. Choisissez en fonction de la part du cycle de vie que vous souhaitez dans un seul outil, et soyez honnête à ce sujet : si vous ne voulez que linter et regrouper dans le terminal, Redocly est plus léger et gratuit.

Si vous voulez essayer l'approche du cycle de vie, téléchargez Apidog et importez une spécification existante ; c'est gratuit pour commencer, aucune carte de crédit n'est requise, et vous pouvez voir votre sortie regroupée et versionnée en quelques minutes.

FAQ

swagger-cli est-il toujours maintenu ?

Non. Le dépôt GitHub de swagger-cli est marqué comme obsolète et n'est plus maintenu, citant une faible contribution par rapport à une large base d'utilisateurs. Il s'installe et fonctionne toujours, mais ne recevra pas de corrections ou de mises à jour, alors prévoyez une migration.

Qu'est-ce qui a remplacé swagger-cli ?

Le README du projet lui-même pointe vers Redocly CLI comme successeur. redocly lint remplace swagger-cli validate et redocly bundle remplace swagger-cli bundle. Redocly publie même un guide de migration dédié. Si vous voulez plus que valider et regrouper, Apidog couvre l'importation, l'exportation, la simulation, les tests et la documentation en un seul endroit.

Apidog est-il gratuit ?

Apidog est freemium. Il existe un niveau gratuit auquel vous pouvez commencer sans carte de crédit, avec des forfaits payants pour les grandes équipes et les besoins avancés. Il n'est pas open source, ce qui est la principale différence avec Redocly CLI et Spectral si une licence ouverte est une exigence pour vous.

Puis-je conserver mon flux de travail swagger-cli tel quel ?

Le plus proche est Redocly CLI. Pour reproduire la validate structurelle simple de swagger-cli, configurez un redocly.yaml avec uniquement la règle spec et exécutez redocly lint. Pour le regroupement, les commandes et les options correspondent presque un à un. Pour un aperçu plus approfondi de la portée de l'outil original, consultez comment utiliser swagger-cli depuis le terminal.