Comment migrer de Swagger CLI vers Apidog CLI

Si vous exécutez encore swagger-cli validate et swagger-cli bundle dans votre pipeline, vous maintenez un script autour d'un outil que personne ne maintient plus. Le référentiel GitHub de swagger-cli l'indique désormais directement : le package n'est plus maintenu, le README cite le fardeau de devoir gérer une énorme base d'utilisateurs qui contribue peu en retour, et il oriente les nouveaux utilisateurs vers d'autres solutions.

C'est donc le bon moment pour décider où votre flux de travail de spécification va se situer par la suite. Ce guide est un runbook de migration, pas un tutoriel d'utilisation. Si vous n'êtes pas prêt à passer à autre chose et que vous voulez simplement continuer à utiliser l'ancien outil, le guide Swagger CLI couvre en détail validate et bundle. Cet article concerne la transition, en particulier la migration de Swagger CLI vers Apidog CLI sans casser votre CI.

Téléchargez Apidog si vous souhaitez suivre avec de vraies commandes. C'est gratuit pour commencer, aucune carte de crédit n'est requise.

Pourquoi migrer maintenant

La réponse honnête d'abord : swagger-cli est déprécié et non maintenu depuis un certain temps. Il fonctionne toujours. Beaucoup de pipelines l'appellent encore aujourd'hui. Mais un outil qui ne recevra pas de corrections de bogues ou de mises à jour de spécifications est une dette technique qui pèse sur votre build, et les mainteneurs eux-mêmes recommandent de passer à autre chose.

Ils désignent un successeur en particulier. Redocly CLI est le remplacement direct le plus proche si tout ce que vous vouliez était "validate" et "bundle" dans le terminal. C'est un outil open source, "code-first" et natif du terminal. Sa commande lint effectue une validation structurelle, et redocly bundle suit les pointeurs $ref exactement comme le faisait swagger-cli bundle. Si votre seul objectif est un échange 1:1 qui maintient la spécification comme un fichier plat dans votre dépôt, Redocly est le choix naturel, et Redocly publie son propre guide de migration avec la correspondance des commandes. Il n'y a aucune honte à suivre cette voie.

Apidog a un objectif différent. Migrez vers Apidog CLI lorsque vous voulez que la spécification fasse plus que rester dans un fichier. Au lieu de valider et de regrouper un document statique, vous intégrez toute la définition dans un espace de travail vivant, puis vous la validez à l'importation, exportez un fichier consolidé lorsque vous en avez besoin, et vous pouvez facultativement simuler l'API, exécuter des scénarios de test et publier la documentation à partir de la même source. swagger-cli ne faisait que deux choses. Apidog couvre le reste du cycle de vie.

Choisissez en fonction de l'adéquation, pas du battage médiatique. Si vous voulez un linter et un bundleur légers et configurables que vous exécutez uniquement depuis le terminal, Redocly gagne. Si vous préférez avoir une seule plateforme pour la conception, la simulation, les tests et la documentation au lieu de combiner plusieurs outils, Apidog gagne.

Ce que faisait swagger-cli et ce que fait Apidog CLI

swagger-cli n'avait que deux commandes :

• swagger-cli validate <fichier> vérifiait un document Swagger 2.0 ou OpenAPI 3.0 par rapport au schéma et vérifiait que ses pointeurs $ref étaient résolus.
• swagger-cli bundle <fichier> suivait ces pointeurs $ref et combinait une définition multi-fichiers en un seul fichier, avec des options pour le chemin de sortie (-o), le type (-t json|yaml), la déréférence complète (-r), et l'indentation (-f).

C'est tout l'outil. Il ne faisait pas de linting avec des règles de style, ne générait pas de documentation, n'exécutait pas de tests, ni ne simulait quoi que ce soit.

Apidog CLI mappe ces deux tâches sur deux de ses commandes, puis va plus loin :

• apidog import ingère une définition dans un projet Apidog et la valide à l'entrée. Les spécifications multi-fichiers avec des pointeurs $ref voient leurs ressources unifiées automatiquement. C'est votre étape de validation, plus l'ingestion.
• apidog export émet un seul fichier consolidé à partir du projet, et vous permet de choisir la version OpenAPI à la sortie. C'est votre étape de bundling, plus une mise à niveau optionnelle de la version et la possibilité d'émettre de la documentation HTML ou Markdown.
• apidog run exécute des scénarios et des suites de tests, avec des rapporteurs JUnit et autres pour la CI. swagger-cli n'avait pas d'équivalent.
• Les commandes de ressources (endpoint, schema, mock, environment, branch, et plus) gèrent le projet depuis le terminal une fois la spécification importée.

Un point précis pour que le mappage reste honnête : Apidog valide la structure à l'importation, mais ce n'est pas un linter de guide de style configurable. Il n'y a pas de apidog lint ni de jeux de règles personnalisés. Si vous vous appuyiez sur un linting strict, cette partie ne se transpose pas, et la section Ce que vous gagnez explique comment le gérer.

Installation et connexion

Apidog CLI est livré sous forme de package npm. Installez-le globalement :

npm install -g apidog-cli@latest

Ensuite, authentifiez-vous avec un jeton d'accès :

apidog login --with-token <TOKEN>

Vous obtenez le jeton depuis l'application ou le web Apidog : cliquez sur votre avatar, allez dans Paramètres du compte, puis Jeton d'accès API, et générez-en un. La CLI le stocke dans ~/.apidog/config.toml. Traitez-le comme n'importe quel autre secret. Ne l'imprimez pas dans les logs et ne le commettez pas dans votre dépôt.

Si vous souhaitez tous les drapeaux et une exploration plus approfondie, le guide complet d'Apidog CLI et la documentation officielle d'Apidog CLI couvrent toute la surface. Pour cette migration, l'installation et la connexion sont tout ce dont vous avez besoin pour commencer.

Table de correspondance des commandes

Voici la traduction directe de swagger-cli vers Apidog CLI. La seule différence structurelle : Apidog fonctionne avec un projet, donc la plupart des flux sont "import-then-export" plutôt qu'une seule commande sur un fichier indépendant.

Les deux cellules les plus importantes pour la migration sont les deux premières lignes. Tout ce qui se trouve en dessous sont des capacités que swagger-cli n'a jamais eues. L'indicateur --oas-version est la mise à niveau la plus claire : swagger-cli pouvait regrouper un fichier Swagger 2.0, mais il ne pouvait pas le transformer en OpenAPI 3.1. Apidog le peut, à l'exportation, ce qui est pratique lorsque vous modernisez un ancien contrat. Si votre objectif est spécifiquement la production de documentation, exporter OpenAPI vers Markdown explore ce format plus en profondeur.

Migration étape par étape

Voici le chemin complet d'une configuration swagger-cli vers un flux Apidog fonctionnel.

1. Obtenez l'ID de votre projet. Créez ou ouvrez un projet dans l'application Apidog. L'ID du projet apparaît dans les paramètres du projet et dans l'URL. Vous le passerez à chaque commande CLI via --project.

2. Importez la spécification racine. Dirigez Apidog vers le fichier d'entrée de votre définition. Les spécifications multi-fichiers avec des pointeurs $ref se résolvent automatiquement, vous importez donc la racine et Apidog extrait le reste :

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

Si la spécification est mal formée ou si un $ref est non résolu, l'importation échoue. Cet échec est votre porte de validation, le même travail que swagger-cli validate effectuait, maintenant intégré à l'ingestion.

3. Vérifiez dans l'application. Ouvrez le projet et confirmez que vos points de terminaison, schémas et paramètres ont été correctement importés. Cette vérification visuelle n'a pas d'équivalent dans swagger-cli, et elle vaut la peine d'être effectuée une fois pendant la migration pour confirmer que l'importation a fait ce que vous attendiez.

4. Exportez le fichier consolidé. Lorsque vous avez besoin d'un seul fichier plat (pour un outil en aval, un générateur de client ou un artefact), exportez-le. Choisissez la version OpenAPI que vous souhaitez :

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

Cela remplace swagger-cli bundle. Les pointeurs $ref étaient déjà résolus à l'importation, donc l'exportation est votre sortie consolidée en un seul fichier.

5. Intégrez-le à la CI. Remplacez votre ancienne étape swagger-cli par l'importation (validation à l'ingestion) et l'exportation (bundle), et ajoutez une exécution de test si vous avez des scénarios. La section suivante contient un exemple complet pour GitHub Actions.

Exemple de CI avec GitHub Actions

Ce workflow installe la CLI, se connecte avec un jeton provenant des secrets du dépôt, importe la spécification pour la valider, exporte un artefact consolidé, puis exécute des scénarios de test avec le rapporteur JUnit afin qu'un test échouant fasse échouer la vérification et bloque la PR.

name: Vérification de la spécification API

on:
  pull_request:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Installer Apidog CLI
        run: npm install -g apidog-cli@latest

      - name: Se connecter
        run: apidog login --with-token ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Importer la spécification (valide à l'importation)
        run: apidog import --project 123456 --format openapi --file ./openapi.yaml

      - name: Exporter la spécification consolidée
        run: apidog export --project 123456 --format openapi --output ./dist/openapi.json --oas-version 3.1

      - name: Exécuter les scénarios de test
        run: apidog run --project 123456 -t 7890 -e 4567 -r "cli,junit" --out-dir ./reports

Stockez le jeton sous le nom APIDOG_ACCESS_TOKEN dans les secrets de votre dépôt afin qu'il n'apparaisse jamais dans les logs. Le rapporteur -r "cli,junit" écrit un fichier XML JUnit que votre CI peut afficher comme rapport de test, et un scénario échouant renvoie un code de sortie non nul qui bloque la fusion. Pour des modèles de pipeline plus approfondis, consultez le guide CI/CD d'Apidog CLI, et pour la configuration spécifique au runner, la procédure pas à pas d'Apidog CLI avec GitHub Actions.

Ce que vous gagnez au-delà de la validation et du regroupement

C'est là que la migration est payante, et où l'honnêteté est la plus importante.

Serveurs de simulation. Une fois votre spécification dans un projet, Apidog peut servir des réponses simulées à partir de celle-ci. Vous pouvez développer un frontend contre l'API avant que le backend n'existe. swagger-cli n'a jamais touché au comportement d'exécution.

Scénarios de test automatisés. apidog run exécute de véritables requêtes contre une API en cours d'exécution et effectue des assertions sur les réponses. Vous construisez visuellement des scénarios dans l'application, puis les exécutez sans interface graphique dans la CI. Cela comble l'écart laissé béant par swagger-cli : une spécification valide vous indique que le contrat est bien formé, pas que l'implémentation y correspond.

Documentation hébergée et exportée. apidog export --format html ou --format markdown produit de la documentation directement à partir de la même source. Aucune étape de création de documentation séparée à maintenir.

Maintenant, la limite honnête. Apidog CLI ne dispose pas d'un linter de guide de style configurable et "code-first" avec des jeux de règles personnalisés. Il valide la structure à l'importation, mais vous ne pouvez pas créer de règles de style Spectral ou Redocly via la CLI, et il n'y a pas de commande apidog lint. Si votre ancienne configuration s'appuyait sur un linting lourd (nommage cohérent, descriptions requises, exemples sur chaque réponse), conservez un linter dédié dans la boucle. Associez Apidog à Spectral ou Redocly pour cela, et exécutez-le comme une étape de CI séparée. Le guide de configuration du linter OpenAPI explique comment en intégrer un. Utiliser les deux n'est pas une contradiction : linting avec un outil spécialisé, puis gestion du cycle de vie dans Apidog.