Redocly CLI est un bon outil. Si vous l'avez utilisé pour linter des fichiers OpenAPI, regrouper une spécification multi-fichiers en un seul, ou construire des documents Redoc depuis le terminal, vous le savez déjà. Alors pourquoi chercher une alternative à Redocly CLI ?
Généralement, tout dépend de la forme. Redocly CLI est un spécialiste ciblé, axé sur le code : lint, bundle, split, join, build docs. C'est exactement ce qu'il faut pour certaines équipes et pas assez pour d'autres. Si vous voulez un seul outil qui conçoit, simule et teste votre API, la CLI n'essaie pas d'être cet outil, et elle ne devrait pas l'être.
Cet article concerne le **Redocly CLI** (le package open-source @redocly/cli), et non le produit de documentation Redocly hébergé. Si vous comparez la plateforme de documentation hébergée ou Redoc lui-même, lisez plutôt notre aperçu des alternatives à Redocly pour la documentation API. Ce billet s'adresse aux personnes qui tapent redocly lint et redocly bundle et veulent savoir ce qui d'autre correspond à leur flux de travail.
Ce que Redocly CLI fait réellement bien
Redocly CLI est open source et natif du terminal. Vous l'installez une fois et obtenez un ensemble concis de commandes qui exécutent leurs tâches proprement. La documentation de Redocly CLI les couvre toutes, mais voici la version courte.
**Le linting est sa force distinctive.** redocly lint valide votre description OpenAPI, AsyncAPI, Arazzo ou Open-RPC, puis exécute des règles de guide de style. Vous configurez tout via un fichier redocly.yaml : choisissez un ensemble de règles intégré (minimal, recommended, recommended-strict ou spec) ou créez vos propres règles personnalisées. Cette gouvernance basée sur la configuration est difficile à battre si vous souhaitez une conception d'API cohérente appliquée en CI à travers de nombreuses équipes.
npm install -g @redocly/cli@latest
redocly lint openapi.yaml
**Bundle, split et join gèrent la plomberie des spécifications.** redocly bundle suit les pointeurs $ref et produit un seul fichier consolidé. redocly split fait l'inverse, en éclatant une description unique en une disposition multi-fichiers. redocly join (expérimental) fusionne plusieurs fichiers OpenAPI en un seul.
redocly bundle openapi.yaml --output dist/openapi.json
**La documentation provient de build-docs.** Elle produit une page HTML Redoc autonome, et preview-docs vous donne un aperçu local en direct.
redocly build-docs openapi.yaml -o docs.html
Donc, si vos besoins sont de « valider par rapport à un guide de style, regrouper la spécification et livrer la documentation Redoc, le tout depuis le terminal », Redocly CLI est un excellent choix par défaut. De nombreuses équipes devraient le conserver. Les raisons de chercher ailleurs concernent la portée, et non la qualité.
Pourquoi les gens cherchent une alternative
Quelques schémas se répètent sans cesse :
- **Vous voulez une plateforme tout-en-un, pas seulement du lint et de la documentation.** Redocly CLI n'exécute pas de tests API et n'héberge pas de serveur de maquette. Si vous avez également besoin de conception, de maquettage et d'un exécuteur de tests, vous assemblez une chaîne d'outils autour de lui.
- **Vous voulez une interface graphique (GUI) à côté de la CLI.** Redocly est conçu pour être axé sur le code. Si votre équipe comprend des personnes qui préfèrent travailler visuellement, une gouvernance uniquement basée sur le terminal est difficile à vendre.
- **Vous voulez un exécuteur de tests intégré pour la CI.** Le linting détecte les problèmes de spécification. Il ne vous dit pas si l'API en cours d'exécution se comporte correctement. C'est un outil séparé.
- **Vous ne voulez pas assembler cinq outils.** Spectral pour le lint, Redocly pour le bundle et la documentation, Postman ou Newman pour les tests, quelque chose d'autre pour les maquettes. Cela fonctionne, mais il y a beaucoup d'éléments à maintenir.
Chacun de ces points renvoie à une alternative différente. Associons-les.
La liste restreinte, selon ce que vous vouliez réellement
Apidog, si vous voulez une plateforme unique pour tout le cycle de vie de l'API
Apidog est une plateforme API tout-en-un : conception, maquettage, test et documentation en un seul endroit, avec une CLI pour l'importation, l'exportation et l'exécution de tests CI. C'est le bon choix lorsque vous préférez avoir un seul outil pour l'ensemble du cycle de vie plutôt que d'assembler un linter, un bundler, un exécuteur de tests et un serveur de maquette.
Voici la partie honnête. **Apidog ne possède pas de linter de guide de style configurable, axé sur le code, avec des ensembles de règles personnalisés comme le lint de Redocly.** Il n'y a pas de commande apidog lint et aucun moyen de créer des règles personnalisées de type Spectral ou Redocly via la CLI. Apidog valide la structure lorsque vous importez une spécification, mais si une gouvernance de conception stricte et personnalisable est la seule chose qui vous importe, Apidog ne remplacera pas redocly lint à lui seul. Associez-le à Spectral pour cette tâche. Nous y reviendrons.
Ce qu'Apidog vous offre que Redocly CLI n'a pas : un concepteur visuel, un serveur de maquette intégré, un constructeur de tests visuels et un exécuteur de tests CI. La CLI gère les parties qui appartiennent à un terminal.
# Install and authenticate (token from the app: avatar > Account Settings > API Access Token)
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
# Import a spec into a project (validates + resolves multi-file $refs)
apidog import --project 123456 --format openapi --file ./openapi.json
# Export a single consolidated file, and pick your OpenAPI version
apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1
# Run a test scenario in CI with multiple report formats
apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"
apidog import effectue la validation à l'ingestion, et apidog export effectue un regroupement à l'exportation (il émet un seul fichier et peut mettre à niveau la version OAS). La liste complète des commandes se trouve dans la documentation d'Apidog CLI, et notre guide complet d'Apidog CLI explique chaque option. Idéal pour : les équipes qui veulent la conception, la simulation, le test et la documentation sous un même toit.
Spectral, si tout ce que vous vouliez de Redocly était le linter
Si la seule chose que vous utilisez est redocly lint, vous n'avez pas besoin de changer de plateforme. Spectral de Stoplight est le linter open-source basé sur des règles qui se chevauche le plus directement avec le linting de Redocly. Vous écrivez des règles en YAML, les exécutez contre n'importe quel document OpenAPI ou AsyncAPI, et l'intégrez à votre CI.
Spectral et le linter de Redocly sont de proches parents. Tous deux sont pilotés par la configuration, livrent des ensembles de règles, et vous permettent de créer des règles personnalisées. Le choix entre eux se résume souvent à l'adéquation à l'écosystème et au format d'ensemble de règles que votre équipe connaît déjà. Notre analyse approfondie sur le linting OpenAPI avec Spectral couvre la création de règles, et le guide plus large sur le linting API compare le paysage du linting si vous voulez avoir une vue d'ensemble. Idéal pour : les équipes dont le besoin réel est un linting de spécifications pur et personnalisable.
Scalar ou Bump.sh, si vous vouliez surtout la documentation
Si la partie de Redocly CLI qui vous intéressait était build-docs, l'alternative est un outil de documentation, pas une plateforme. Scalar et Bump.sh transforment tous deux une description OpenAPI en documentation de référence hébergée et navigable, chacun avec son propre look et ensemble de fonctionnalités. Ils se concentrent sur l'expérience de la documentation plutôt que sur le linting ou les tests. Idéal pour : les équipes dont l'objectif principal est une documentation de référence API esthétique et maintenable.
swagger-cli, qui n'est plus vraiment une option
Vous verrez encore swagger-cli mentionné dans d'anciens guides, il est donc important de préciser : **swagger-cli est déprécié.** Le dépôt GitHub de swagger-cli indique qu'il n'est plus maintenu et renvoie les utilisateurs vers Redocly CLI comme successeur.
Il n'a toujours eu que deux commandes, swagger-cli validate et swagger-cli bundle. Il n'a jamais effectué de linting avec des règles de style, jamais généré de documentation, jamais exécuté de tests, et jamais simulé quoi que ce soit. Si vous l'utilisez aujourd'hui, le but est de l'abandonner, pas de l'adopter. Notre guide sur comment utiliser swagger-cli couvre ce qu'il faisait, et Redocly publie même un guide de migration de swagger-cli avec la correspondance exacte des options. Nous inclurons cette correspondance ci-dessous pour être complet.
Tableau comparatif
Voici comment les options se comparent aux tâches gérées par Redocly CLI. « Lint règles personnalisées » signifie un linter de guide de style configurable, axé sur le code, avec des ensembles de règles personnalisés.
| Outil | Lint règles personnalisées | Bundle | Docs | Maquette | Test | GUI | Open source | Idéal pour |
|---|---|---|---|---|---|---|---|---|
| Redocly CLI | Oui | Oui | Oui (Redoc) | Non | Non | Non | Oui | Gouvernance du lint, bundle et docs axée sur le code depuis le terminal |
| Apidog | Non | Via export | Oui | Oui | Oui (exécuteur CI) | Oui | Non (freemium) | Une plateforme unique pour la conception, la simulation, le test et la documentation |
| Spectral | Oui | Non | Non | Non | Non | Non | Oui | Linting OpenAPI/AsyncAPI pur et personnalisable |
| Scalar / Bump.sh | Non | Non | Oui | Non | Non | Oui | Variable | Documentation de référence API hébergée |
| swagger-cli | Non | Oui | Non | Non | Non | Non | Oui (déprécié) | Rien de nouveau, il n'est plus maintenu |
Une note sur le tableau : Le « Via export » d'Apidog signifie que apidog export émet un fichier consolidé, ce qui couvre la raison pratique pour laquelle vous exécuteriez redocly bundle, mais ce n'est pas une commande bundle équivalente. Et Apidog est freemium, pas open source, tandis que Redocly CLI et Spectral sont tous deux open source. Appelez ces compromis par leur nom.
Correspondance des options de bundle de swagger-cli à Redocly CLI
Si vous utilisez swagger-cli (déprécié) et que Redocly est votre destination pour le regroupement, les options correspondent clairement :
| swagger-cli | Redocly CLI | Signification |
|---|---|---|
-o, --outfile <file> |
--output (ou -o) |
Écrire dans un fichier au lieu de la sortie standard |
-t, --type <json|yaml> |
--ext <json|yaml|yml> |
Type de fichier de sortie |
-r, --dereference |
-d, --dereferenced |
Intégrer complètement tous les $refs |
Ainsi, swagger-cli bundle -o output.json devient redocly bundle --output output.json.
Une recommandation claire
Il n'y a pas de gagnant unique, car la bonne réponse dépend de la tâche de Redocly CLI que vous essayez de remplacer.
**Conservez Redocly CLI** si sa gouvernance est exactement ce dont vous avez besoin. Un linter, un bundler et un constructeur de documentation Redoc légers, open-source et pilotés par la configuration, que vous exécutez purement depuis le terminal, constituent une configuration réellement efficace. Rien ici n'est une raison d'abandonner un outil qui convient.
**Choisissez Apidog** si vous êtes fatigué d'assembler une chaîne d'outils et que vous voulez la conception, la simulation, le test et la documentation sur une seule plateforme avec une CLI pour les parties liées au terminal. Vous arrêtez de maintenir des outils séparés pour chaque étape et obtenez une interface graphique (GUI) pour les membres de votre équipe qui en veulent une. Soyez simplement conscient que vous l'associerez à Spectral si vous avez également besoin d'un linting avec des règles personnalisées. Le guide Apidog CLI en CI/CD montre comment l'exécuteur de tests s'intègre dans un pipeline, et Apidog CLI vs Newman le compare à l'exécuteur que de nombreuses équipes utilisent déjà. Vous pouvez télécharger Apidog et l'essayer gratuitement, sans carte de crédit.
**Choisissez Spectral** si le linting est le seul objectif. Ne changez pas de plateforme pour remplacer une seule commande.
Pour être honnête : Redocly est un spécialiste de la CLI axé sur le code, et Apidog est une plateforme visuelle tout-en-un. Ce sont des paradigmes différents, pas un remplacement direct. Choisissez en fonction de vos besoins.
FAQ
**Apidog est-il un remplacement direct pour Redocly CLI ?** Non, et il vaut mieux être honnête à ce sujet. Apidog couvre une plus grande partie du cycle de vie (conception, simulation, test, documentation) mais n'a pas de linter avec des ensembles de règles personnalisés comme redocly lint. Si une gouvernance de spécification stricte et configurable est votre tâche principale, conservez le linter de Redocly ou utilisez Spectral. Apidog est avantageux lorsque vous voulez un seul outil pour l'ensemble du cycle de vie de l'API au lieu de plusieurs.
**Apidog CLI a-t-il une commande lint ?** Non. Apidog valide la structure lorsque vous importez une spécification avec apidog import, mais il n'y a pas de apidog lint et aucun moyen de créer des règles personnalisées de type Spectral ou Redocly via la CLI. Pour cela, associez Apidog à Spectral.
**Puis-je regrouper un fichier OpenAPI sans Redocly CLI ?** Oui. apidog export --project <id> --format openapi --output ./openapi.json émet un seul fichier consolidé et peut cibler une version OpenAPI spécifique avec --oas-version. Ce n'est pas une commande bundle littérale, mais elle répond au même besoin pratique. Si vous ne voulez que le regroupement et rien d'autre, redocly bundle reste un excellent choix ciblé.
**Devrais-je utiliser swagger-cli en 2026 ?** Non. swagger-cli est déprécié et non maintenu, et son propre dépôt renvoie vers Redocly CLI comme successeur. Il ne faisait que valider et regrouper. Utilisez Redocly CLI pour cette tâche, ou passez à une plateforme comme Apidog si vous voulez le reste du cycle de vie également.
**Quelle est la différence entre ceci et la comparaison de la plateforme de documentation Redocly ?** Ce billet concerne l'outil open-source @redocly/cli : lint, bundle, split, join, et build-docs. Si vous comparez le produit de documentation Redocly hébergé ou Redoc en tant que moteur de rendu de documentation, lisez plutôt les alternatives à Redocly pour la documentation API. Les deux couvrent des produits différents qui se trouvent partager un nom. Pour la spécification elle-même, la spécification OpenAPI est la source de vérité, et la CLI Redocly sur npm est l'endroit où vous trouverez les détails d'installation actuels.