Swagger CLI : Valider, Linter et Tester votre Spécification API en Ligne de Commande

Vous avez ouvert une pull request, la documentation a été générée correctement, et trois jours plus tard un coéquipier vous contacte : le serveur de staging rejette chaque requête car le fichier OpenAPI contient un $ref orphelin qui pointe vers un chemin que vous avez renommé. La spécification semblait correcte dans l'éditeur. Elle s'affichait dans Swagger UI. Mais elle n'était tout simplement pas réellement valide, et rien dans votre pipeline ne l'a détecté avant le déploiement.

C'est précisément pour cela qu'un outil en ligne de commande Swagger est conçu : détecter les spécifications défectueuses avant qu'un humain ne le fasse. L'expression « swagger cli » fait généralement référence à @apidevtools/swagger-cli, un petit package npm dont les deux commandes, validate et bundle, vérifient un document OpenAPI et fusionnent des spécifications multi-fichiers en un seul. C'est un outil véritablement utile, et ce guide vous montre comment l'utiliser correctement. Il vous indique également ses limites, car la validation d'une spécification n'est que la première moitié de la confiance en une API ; la seconde moitié consiste à envoyer de vraies requêtes et à vérifier ce qui est renvoyé, et c'est là qu'un exécutant comme l'Apidog CLI prend le relais.

Il s'agit donc en réalité d'un travail nécessitant deux terminaux. Tout d'abord, nettoyez (lint) et regroupez (bundle) la spécification avec swagger-cli (ou son successeur) pour que le contrat soit solide. Ensuite, exécutez des tests réels sur l'API en cours d'exécution depuis la ligne de commande afin de vous assurer que l'implémentation correspond au contrat. Nous couvrirons les deux, serons honnêtes quant à l'outil qui gère quelle tâche, et vous donnerons des commandes à copier-coller pour chacun.

À quoi fait réellement référence « swagger cli »

Il n'existe pas de binaire officiel unique appelé « swagger ». Ce nom renvoie à plusieurs outils différents, et savoir lequel vous utilisez permet d'éviter bien des confusions.

• @apidevtools/swagger-cli est le package que la plupart des gens désignent. Son binaire est swagger-cli, et il fait deux choses : valider un document OpenAPI ou Swagger 2.0, et regrouper une spécification multi-fichiers en un seul. C'est l'objet de la première partie de cet article.
• swagger-codegen est un projet SmartBear distinct, beaucoup plus vaste, qui génère des SDK clients et des stubs de serveur à partir d'une spécification. C'est un travail entièrement différent ; nous en parlerons à la fin.
• Swagger UI et Swagger Editor ne sont pas du tout des CLI. Ils affichent et éditent les spécifications dans un navigateur. Si vous apprenez encore le format, l'amorce Swagger et OpenAPI est le bon point de départ.

Ce guide traite du travail en ligne de commande : valider, regrouper, analyser (lint), puis tester. Si vous souhaitez un aperçu plus large des plateformes de conception et de test, le tour d'horizon des alternatives à Swagger couvre l'aspect GUI.

Installation de swagger-cli

L'outil est distribué sous forme de package npm. Installez-le globalement :

npm install -g @apidevtools/swagger-cli

Confirmez qu'il est résolu :

swagger-cli --version
swagger-cli --help

Node.js est la seule dépendance système. Toute machine ou image CI avec Node déjà installé peut l'exécuter. Si vous préférez ne pas l'installer globalement, vous pouvez l'appeler à la demande avec npx @apidevtools/swagger-cli ..., ce qui est pratique sur les exécutants de build éphémères.

Une chose à savoir avant de vous y fier : les mainteneurs ont marqué swagger-cli comme déprécié. Le README le dit clairement, citant le fardeau de maintenance d'une large base d'utilisateurs avec peu de contributeurs. Il fonctionne toujours, et de nombreux pipelines l'utilisent aujourd'hui, mais les nouveaux projets sont orientés vers Redocly CLI comme successeur activement maintenu. Nous couvrirons cette migration dans une section dédiée ci-dessous, afin que vous puissiez décider en toute connaissance de cause.

Validation d'une spécification avec swagger-cli

La commande principale est validate. Pointez-la vers votre fichier de spécification :

swagger-cli validate openapi.yaml

Si le document est sain, vous obtenez une confirmation sur une ligne et un code de sortie de 0. Si quelque chose ne va pas, vous obtenez une erreur décrivant le problème et un code de sortie non nul, ce qui est exactement ce que vous voulez dans un pipeline.

validate exécute deux vérifications en arrière-plan, et vous pouvez désactiver l'une ou l'autre :

swagger-cli validate --no-schema openapi.yaml
swagger-cli validate --no-spec openapi.yaml

--no-schema ignore la validation par rapport au schéma JSON OpenAPI, la vérification structurelle qui confirme que votre document a la bonne forme. --no-spec ignore la validation par rapport aux règles de la spécification elles-mêmes, la vérification sémantique qui détecte des choses comme des ID d'opération en double ou un $ref qui ne pointe nulle part. La plupart du temps, vous voulez que les deux soient activés, ce qui est le comportement par défaut. Les drapeaux existent pour les cas rares où une couche signale quelque chose que vous avez une raison délibérée d'autoriser.

Ce que validate détecte bien : YAML mal formé, champs obligatoires manquants, pointeurs $ref cassés et erreurs structurelles qui rendent une spécification impossible à analyser. Ce qu'il ne fait pas, c'est d'appliquer le style de votre équipe. Il validera sans problème une spécification sans descriptions, avec des noms incohérents et sans exemples, car rien de tout cela ne viole les règles OpenAPI. Pour ce type de vérification exigeante, vous avez besoin d'un linter, ce qui est l'objet de la section suivante.

Si la validation est la seule chose qui vous intéresse, l'exploration plus approfondie sur comment valider les spécifications OpenAPI compare plusieurs outils et cas limites à connaître.

Regrouper une spécification multi-fichiers

Les spécifications réelles résident rarement dans un seul fichier. Vous divisez les schémas en un répertoire components/, les référencez avec $ref, et conservez le fichier racine lisible. C'est une bonne pratique, mais de nombreux outils en aval souhaitent un document unique et autonome. La commande bundle aplatit l'arborescence :

swagger-cli bundle openapi.yaml -o dist/openapi.bundled.yaml -t yaml

Les drapeaux (options) à connaître :

• -o, --outfile <file> écrit le résultat dans un fichier au lieu de l'afficher sur la sortie standard.
• -t, --type <json|yaml> définit le format de sortie. La valeur par défaut est json, alors passez -t yaml si vous voulez du YAML.
• -r, --dereference insère complètement chaque $ref au lieu de simplement rassembler les fichiers externes en un seul document. Cela produit un fichier plus volumineux sans références restantes, ce que certains consommateurs exigent.
• -f, --format <spaces> contrôle l'indentation, par défaut à 2 espaces.
• -w, --wrap <column> définit la longueur de ligne pour l'habillage des longues chaînes YAML.

La distinction entre un regroupement simple et --dereference est importante. Un regroupement normal conserve les pointeurs $ref internes mais rassemble tous les fichiers séparés en un seul, de sorte que le document est portable. --dereference résout chaque référence en objets intégrés, ce qui augmente la taille du fichier mais garantit qu'aucun consommateur n'aura jamais à résoudre un pointeur. Utilisez le regroupement simple pour la distribution et la forme déréférencée uniquement lorsqu'un outil spécifique l'exige.

Un modèle courant consiste à valider et regrouper en une seule étape dans le cadre d'un build :

swagger-cli validate openapi.yaml && swagger-cli bundle openapi.yaml -o dist/openapi.json

Le && signifie que le regroupement ne s'exécute que si la validation réussit, de sorte qu'une spécification défectueuse ne produit jamais d'artefact de build.

Intégrer swagger-cli dans la CI

La validation est plus précieuse lorsqu'elle s'exécute à chaque changement, et non lorsque quelqu'un s'en souvient. Intégrez-la dans votre pipeline comme une porte rapide. Voici une étape GitHub Actions qui fait échouer le build en cas de spécification invalide :

name: Validate OpenAPI spec

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'components/**'

jobs:
  validate-spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate spec
        run: npx @apidevtools/swagger-cli validate openapi.yaml

Parce que swagger-cli validate renvoie un code de sortie non nul en cas de spécification défectueuse, l'étape devient rouge et la pull request affiche une vérification échouée. Aucune configuration supplémentaire. Le filtre paths empêche l'exécution du job si la spécification n'a pas changé, ce qui réduit vos minutes de CI.

C'est la porte de qualité la moins chère que vous puissiez ajouter à un dépôt d'API. Cela ne coûte que quelques secondes et empêche toute une catégorie de bugs « la documentation a menti » d'atteindre les utilisateurs en aval.

Quand vous avez besoin de linting, pas seulement de validation

La validation répond à une question : s'agit-il d'un document OpenAPI légal ? Le linting répond à une question plus difficile : s'agit-il d'un bon document OpenAPI selon les normes de notre équipe ? Ce n'est pas la même chose, et swagger-cli ne fait que le premier.

Supposons que votre guide de style exige que chaque opération ait un summary, chaque propriété une description, et que chaque chemin utilise le format kebab-case. Une spécification peut violer les trois et passer quand même swagger-cli validate, car aucune de ces règles ne fait partie de la spécification OpenAPI. Un linter vous permet de les coder et de les appliquer.

C'est la principale raison pour laquelle les équipes se tournent vers Redocly CLI, le successeur maintenu vers lequel swagger-cli lui-même vous oriente. Il couvre la même validation et le même regroupement, puis ajoute un véritable moteur de linting en plus.

Migration vers Redocly CLI

La migration est minime car les noms des commandes sont proches. Installez le successeur :

npm install -g @redocly/cli

L'équivalent de validate est lint. Pour correspondre fidèlement à l'ancien comportement, étendez l'ensemble de règles minimales :

redocly lint --extends=minimal openapi.yaml

Exécutez-le plutôt avec l'ensemble de règles par défaut et il appliquera un ensemble plus strict de règles recommandées, ce qui révèle la valeur du linting. Vous configurez les règles dans un fichier redocly.yaml, définissez chacune sur error ou warn, et pouvez même écrire des plugins personnalisés pour des vérifications spécifiques à votre organisation.

Le regroupement (bundling) correspond presque un pour un :

redocly bundle openapi.yaml -o dist/openapi.yaml

Les noms des drapeaux (options) changent légèrement. swagger-cli’s -o/--outfile devient --output, -t/--type devient --ext, et -r/--dereference devient -d/--dereferenced. Si vos anciens scripts utilisaient les drapeaux courts, un rapide rechercher-remplacer vous y mènera. Pour une comparaison plus large des outils de vérification de spécifications, l'aperçu des meilleurs outils de validation OpenAPI place Redocly aux côtés des alternatives.

En bref : si vous débutez, optez pour Redocly CLI. Si vous avez une étape swagger-cli existante qui fonctionne, il n'y a pas d'urgence, mais la voie à suivre est claire et le renommage est mécanique.

La moitié qu'un outil de spécification ne peut couvrir

Voici la limite de tous les outils que nous avons abordés jusqu'à présent. swagger-cli validate confirme que votre spécification est bien formée. redocly lint confirme qu'elle respecte votre style. Aucun des deux n'envoie une seule requête à votre API en cours d'exécution. Une spécification peut être parfaite sur le papier tandis que l'implémentation renvoie une erreur 500, omet un champ promis, ou ignore entièrement un paramètre de requête.

Combler cette lacune signifie effectuer des tests fonctionnels : envoyer une vraie requête à un vrai endpoint, puis vérifier le code de statut, le corps de la réponse et les valeurs qu'il contient. C'est une catégorie d'outil différente, et c'est là que Apidog s'intègre dans le flux de travail.

Apidog est une plateforme API tout-en-un. Vous importez votre spécification OpenAPI, et à partir de cette définition unique, vous obtenez des documents interactifs, un serveur mock, et des scénarios de test que vous pouvez enchaîner avec des assertions, le tout sans quitter l'espace de travail. L'importation est directe ; le guide sur l'importation de Swagger ou OpenAPI et la génération de requêtes exécutables vous explique comment faire, et vous pouvez générer des collections de tests complètes directement à partir de la spécification au lieu de les construire manuellement.

La partie qui compte pour le terminal est l'exécuteur en ligne de commande, publié sous forme de package npm apidog-cli. Vous l'installez et exécutez un scénario enregistré sans interface graphique :

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

L'option -t est l'ID du scénario de test, -e est l'ID de l'environnement, et -r sélectionne les formats de rapport tels que cli, html, json ou junit. Comme swagger-cli, il se termine avec un code de statut propre, donc une assertion échouée fait passer le pipeline au rouge. Contrairement à swagger-cli, ce qu'il vérifie est le comportement en direct de votre API, et pas seulement la forme du fichier qui la décrit. Pour la référence complète des options et des exemples CI, consultez le guide complet d'Apidog CLI, ou exécutez apidog run --help pour les options actuelles. Si vous souhaitez configurer ce premier scénario, téléchargez Apidog, importez votre spécification, et la commande de l'exécuteur se trouve dans l'onglet CI/CD du scénario.

Un workflow terminal complet

Assemblez les deux moitiés et vous obtenez un pipeline qui vérifie le contrat et l'implémentation en séquence :

# 1. La spécification est-elle bien formée et conforme au style ?
redocly lint --extends=minimal openapi.yaml

# 2. Produire un document distribuable unique.
redocly bundle openapi.yaml -o dist/openapi.yaml

# 3. L'API en cours d'exécution correspond-elle réellement au contrat ?
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit

La première étape échoue rapidement sur une spécification mal formée ou non conforme au style. La deuxième étape produit l'artefact que vos générateurs de documentation et de SDK consomment. La troisième étape envoie du trafic réel et vérifie les réponses, de sorte qu'un build réussi signifie que le contrat et le code sous-jacent sont solides. Chaque étape se termine avec un code de sortie non nul en cas d'échec, de sorte que toute la chaîne est une seule porte que vous pouvez intégrer à n'importe quel runner CI disposant de Node.

Si vos tests actuels reposent sur un outil de conformité des spécifications qui est devenu silencieux, l'article sur la validation d'une API par rapport à sa spécification sans Dredd couvre la même idée de contrat contre implémentation sous un angle différent.

Une note sur swagger-codegen

Les personnes recherchant un « swagger cli » veulent parfois en fait swagger-codegen, qui est un outil différent avec une tâche différente. Il lit une spécification OpenAPI et génère des SDK clients, des stubs de serveur et de la documentation dans des dizaines de langages. Il est véritablement utile pour amorcer un client typé à partir d'une spécification publiée, et il est juste de l'appeler l'option de génération de code la plus performante de la famille Swagger.

Il ne valide pas, n'analyse pas (lint) et ne teste pas au sens de cet article. La génération suppose que vous avez déjà une spécification solide ; si l'entrée est défectueuse, la sortie le sera de manière correspondante. Ainsi, même dans un workflow de génération de code, vous souhaitez toujours une étape de validation ou de linting en amont. Les outils se complètent plutôt que de se remplacer mutuellement.