Apidog CLI vs Redocly CLI : quel CLI API utiliser ?

Ces deux outils résident dans votre terminal, parlent tous deux OpenAPI, et se manifestent lorsqu'une équipe décide d'adopter un flux de travail en ligne de commande pour ses spécifications d'API. C'est là que leurs similarités s'arrêtent. Ils résolvent des problèmes adjacents depuis des directions opposées, et choisir le mauvais signifie soit se battre avec un linter qui n'exécute pas de tests, soit opter pour une plateforme alors que tout ce que vous vouliez était une vérification structurelle rapide.

Ceci est une comparaison directe, au niveau des commandes, entre l'interface CLI d'Apidog et l'interface CLI de Redocly. Pas de sophismes. L'interface CLI de Redocly est un excellent logiciel open source, et vous verrez exactement où elle brille avant tout verdict.

Verdict en bref

Ils résolvent des problèmes qui se chevauchent mais sont différents.

Redocly CLI (@redocly/cli, binaire redocly) est un spécialiste OpenAPI "code-first" : il valide (lint) avec des ensembles de règles personnalisés, regroupe des spécifications multi-fichiers, les divise et les joint, et construit des documentations HTML autonomes. C'est un logiciel open source, piloté par la configuration et natif du terminal. Si votre spécification est la source de vérité et réside dans Git, c'est une gouvernance que vous exécutez depuis la ligne de commande.

Apidog CLI (apidog-cli, binaire apidog) est l'interface en ligne de commande d'une plateforme API tout-en-un. Il importe et exporte des définitions pour un projet et exécute des scénarios de test d'API en CI avec des rapports JUnit et HTML. Il trouve sa place lorsque la même spécification doit également être simulée, testée et documentée dans un seul espace de travail au lieu d'être assemblée à partir d'outils séparés.

Choisissez Redocly CLI si vous voulez un linter, un bundler et un constructeur de documentation léger et open source que vous utilisez uniquement depuis le terminal. Choisissez Apidog si vous préférez avoir un seul outil pour l'ensemble du cycle de vie des API. Ils peuvent également fonctionner côte à côte, et la dernière section explique comment.

Deux philosophies différentes

Redocly CLI est centré sur les fichiers et axé sur le code (code-first). Le document OpenAPI sur le disque est l'objet de votre action. Chaque commande, redocly lint, redocly bundle, redocly build-docs, prend un chemin vers un fichier et effectue son travail localement, sans compte ni serveur impliqué. Le comportement est défini par un fichier de configuration redocly.yaml que vous enregistrez dans le dépôt à côté de la spécification. Ce modèle convient aux équipes qui traitent leur description d'API comme du code source : revue dans les requêtes de tirage (pull requests), contrôlée en CI, versionnée comme tout le reste. La Spécification OpenAPI est le contrat, et Redocly CLI est la chaîne d'outils qui l'encadre.

Apidog est centré sur les projets et axé sur la plateforme (platform-first). Vous concevez des points de terminaison, construisez des serveurs de maquette et créez des scénarios de test visuellement dans l'application de bureau ou web, et l'interface CLI est l'interface sans tête (headless) pour une partie de ce travail. La plupart des commandes CLI opèrent sur un projet Apidog sur le serveur, identifié par un ID de projet et authentifié avec un jeton d'accès. La spécification n'est pas un fichier lâche que vous validez sur place ; elle est importée dans un espace de travail vivant où elle peut également être simulée, testée et publiée en tant que documentation. Un seul environnement, plusieurs tâches.

Aucune philosophie n'est fausse. Elles conviennent à différentes équipes. La distinction honnête est la suivante : Redocly vous offre une CLI open source et ciblée pour la gouvernance des spécifications, et Apidog vous offre une CLI pour une plateforme plus large.

Commande par commande

Voici la partie importante, organisée tâche par tâche. Chaque commande ci-dessous est réelle ; rien n'est inventé.

Quelques-unes de ces lignes méritent une note simple, car la différence est réelle et l'article serait malhonnête sans cela.

La validation (linting) est le domaine de prédilection de Redocly, pas d'Apidog. Redocly CLI valide les spécifications OpenAPI, AsyncAPI, Arazzo et Open-RPC par rapport à des ensembles de règles configurables, et vous pouvez créer vos propres règles. Apidog valide la structure d'une définition lorsque vous l'importez, mais il n'y a pas de commande apidog lint, pas de configuration de style redocly.yaml, et aucun moyen d'écrire des règles de guide de style personnalisées via la CLI. Si votre objectif est un guide de style "code-first" appliqué dans le terminal, Redocly est l'outil. Apidog ne rivalise pas ici, et affirmer le contraire serait faux.

La division et la jointure appartiennent à Redocly. redocly split éclate une description en une structure multi-fichiers, et redocly join (expérimental) fusionne plusieurs fichiers en un seul. Apidog n'a aucune de ces commandes. Son importation résout les $refs multi-fichiers en ressources unifiées, et son exportation génère un seul fichier consolidé, mais ce n'est pas la même chose qu'un utilitaire autonome de division/jointure que vous exécutez sur des fichiers isolés.

L'exécution de tests et le mocking appartiennent à Apidog. Redocly CLI n'exécute pas de tests d'API et n'héberge pas de serveur de maquette ; cela est intentionnellement hors de son champ d'application. Apidog exécute des scénarios de test sans interface (headless) avec apidog run et produit des rapports JUnit, HTML, JSON et CLI pour votre pipeline, et le mocking est une fonctionnalité de premier ordre de la plateforme (créé dans l'application, non piloté depuis la CLI).

Les deux génèrent des documents HTML depuis le terminal. redocly build-docs produit un fichier HTML Redoc autonome. apidog export --format html écrit un fichier de documentation HTML à partir de votre projet. Moteurs différents, même résultat dans le terminal.

Commandes Redocly CLI réelles

Installez-le globalement, ou ignorez l'installation et exécutez-le via npx :

npm install -g @redocly/cli@latest
# ou, pas d'installation globale :
npx @redocly/cli@latest lint openapi.yaml

Validez une spécification. Avec un fichier redocly.yaml présent, cela applique l'ensemble de règles choisi (minimal, recommended, recommended-strict, spec, ou des règles personnalisées) :

redocly lint openapi.yaml

Si vous ne souhaitez qu'une simple validation structurelle, comme celle que faisait l'obsolète swagger-cli, configurez redocly.yaml avec seulement la règle spec et exécutez le même redocly lint. Redocly publie un guide de migration depuis swagger-cli car Redocly CLI est son successeur désigné. Le dépôt swagger-cli affiche désormais un avis d'obsolescence pour la même raison ; cet ancien outil ne faisait que valider et regrouper, jamais de validation de style.

Regroupez une définition multi-fichiers en un seul fichier, en suivant chaque $ref :

redocly bundle openapi.yaml --output bundled.json

Si vous venez de swagger-cli, les drapeaux correspondent proprement : -o/--outfile devient --output, -t/--type devient --ext (json, yaml, ou yml), et -r/--dereference devient -d/--dereferenced.

Générez une documentation HTML autonome avec Redoc :

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

Divisez une description unique en une mise en page multi-fichiers, l'inverse du regroupement :

redocly split openapi.yaml --outDir ./split-spec

Pour une vue plus large de la comparaison de Redocly avec d'autres outils de cette catégorie, le guide de configuration du linter OpenAPI couvre Spectral, Redocly et Vacuum côte à côte, et la synthèse des alternatives à Redocly couvre spécifiquement la plateforme de documentation.

Commandes Apidog CLI réelles

Installez l'interface CLI et authentifiez-vous avec un jeton de l'application (avatar, puis Paramètres du compte, puis Jeton d'accès API) :

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

Le jeton est enregistré dans ~/.apidog/config.toml. Ne l'affichez pas et ne le committez pas.

Importez une définition dans un projet. Cela valide la structure et l'ingère, résolvant les $refs multi-fichiers en ressources unifiées :

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

L'importation accepte plus que l'OpenAPI : Postman, HAR, Insomnia, JMeter, WSDL, YApi, RAP2, apiDoc, Hoppscotch, Markdown, JSON Schema, et le propre format d'Apidog.

Exportez un seul fichier consolidé, en option avec une mise à niveau de la version OpenAPI. Il s'agit d'un regroupement plus une éventuelle mise à jour de version en une seule étape :

apidog export --project 123456 --format openapi --output ./openapi.json --oas-version 3.1

Exportez la documentation HTML directement depuis le projet :

apidog export --project 123456 --format html --output ./docs.html

Exécutez un scénario de test en CI et générez des rapports que votre pipeline peut lire :

apidog run --project 123456 -t <testScenarioId> -e <environmentId> -r "cli,html,json,junit"

Vous pouvez également exécuter entièrement hors ligne à partir d'un fichier de collection exporté, sans projet ni jeton nécessaire :

apidog run ./collection.apidog-cli.json

La référence complète des drapeaux, y compris --out-dir, -n/--iteration-count, -d/--iteration-data, et --env-var, se trouve dans le guide complet d'Apidog CLI. La documentation officielle d'Apidog CLI couvre l'installation et chaque commande de ressource. Pour une comparaison de runners en CI, voir Apidog CLI vs Newman et Bruno CLI vs Apidog CLI.

Quand choisir Redocly CLI

Optez pour Redocly CLI lorsque la spécification est votre source de vérité et que vous souhaitez la gérer comme du code.

Vous voulez un véritable linter avec des règles personnalisées. La commande lint de Redocly et sa configuration redocly.yaml sont la caractéristique principale : choisissez un ensemble de règles intégré ou écrivez le vôtre, et appliquez les conventions de nommage, les champs obligatoires et le style maison à chaque commit. Rien dans la CLI d'Apidog ne correspond à cela. Si la gouvernance de style native au terminal est la tâche, Redocly est la réponse.

Vous voulez de l'open source sans compte. La CLI fonctionne entièrement sur votre machine ou sur un runner CI. Pas de connexion, pas de jeton, pas d'appel au serveur pour lint, bundle, split ou build-docs. Pour les environnements air-gapped ou les règles strictes de traitement des données, c'est une exigence difficile que Redocly respecte et qu'une CLI de plateforme ne respecte généralement pas.

Vous voulez une chaîne d'outils légère et ciblée. Si tout ce dont vous avez besoin est le linting, le regroupement, la division, la jointure et la documentation HTML depuis le terminal, Redocly fait exactement cela et rien de plus. Vous pouvez l'installer ou l'exécuter via npx sans aucune configuration. L'ensemble complet des commandes se trouve dans la documentation Redocly CLI et la page du paquet npm.

Quand choisir Apidog

Optez pour Apidog lorsque la spécification fait partie d'un cycle de vie plus vaste que vous préférez ne pas assembler à partir d'outils séparés.

Vous voulez la conception, la maquette, les tests et la documentation en un seul endroit. La CLI importe votre spécification, exporte un fichier consolidé propre à la version OpenAPI de votre choix et exécute des scénarios de test en CI. Le même projet vous offre également une conception visuelle, un serveur de maquette et une documentation publiée, le tout partageant une seule définition. Vous cessez de câbler un linter, un outil de maquette, un exécuteur de tests et un générateur de documentation.

Vous voulez l'exécution de tests dans votre pipeline avec des rapports utilisables. apidog run produit du XML JUnit pour votre tableau de bord CI, ainsi que des artefacts HTML et JSON, et se termine avec un code d'erreur non nul lorsqu'un test échoue. Redocly n'exécute pas de tests du tout, donc si le contrôle des tests CI est sur votre liste, c'est là qu'Apidog s'intègre. Les modèles de validation OpenAPI en CI s'associent naturellement à un test exécuté sur le même pipeline.

Vous voulez une source de vérité unique pour toute une équipe. Les ressources résident dans un projet Apidog où concepteurs, testeurs et rédacteurs travaillent tous. La CLI est la surface d'automatisation de cet espace de travail partagé, ce qui convient aux équipes qui préfèrent collaborer sur une plateforme plutôt que de se transmettre des fichiers de spécification.

Téléchargez Apidog pour suivre. C'est gratuit pour commencer, aucune carte de crédit requise.

Ils peuvent être complémentaires

Il ne s'agit pas strictement d'un choix exclusif, et prétendre que c'est le cas manquerait la configuration la plus pratique.

Un flux de travail efficace exécute Redocly CLI (ou Spectral) comme passerelle de linting en CI, appliquant votre guide de style sur chaque pull request, et utilise Apidog pour la conception, le mocking, l'exécution des tests et la documentation publiée. Validez (lint) là où le linting est le meilleur, avec des ensembles de règles open source dans le terminal. Simulez, testez et documentez là où une plateforme est la meilleure. La spécification circule entre eux : validez le fichier en CI, importez-le dans Apidog pour tout ce qui est en aval.

Cette combinaison exploite la véritable force de chaque outil au lieu de forcer l'un à faire le travail de l'autre.

FAQ

Apidog CLI dispose-t-il d'une commande de linting avec des règles personnalisées comme Redocly ?

Non. Apidog valide la structure d'une définition lorsque vous l'importez, mais il n'y a pas de commande apidog lint et aucun moyen de créer des règles de guide de style personnalisées via la CLI. Pour un linting configurable et "code-first", utilisez Redocly CLI ou Spectral.

Redocly CLI peut-il exécuter des tests d'API en CI ?

Non. Redocly CLI valide (lint), regroupe (bundle), divise (split), joint (join) et construit des documents. Il n'exécute pas de tests d'API et n'héberge pas de serveur de maquette. Pour les exécutions de tests sans interface (headless) avec des rapports JUnit et HTML, utilisez apidog run.

Apidog est-il open source comme Redocly CLI ?

Non. Redocly CLI et Spectral sont open source. Apidog est freemium : la CLI est gratuite à installer depuis npm, mais elle fonctionne avec un compte et un projet Apidog plutôt que comme un logiciel entièrement open source.

J'utilisais swagger-cli pour la validation et le regroupement. Vers quoi devrais-je me tourner ?

Les deux outils couvrent ces fonctionnalités. Redocly CLI est le successeur désigné de swagger-cli, avec redocly lint (configurez la règle spec pour une validation simple) et redocly bundle. Apidog couvre le même terrain via apidog import (validation) et apidog export (regroupement, avec une mise à jour optionnelle de la version OpenAPI), et ajoute le mocking, les tests et la documentation dans le même espace de travail.