Un fichier Swagger corrompu s'annonce rarement. Le fichier YAML s'analyse correctement. La page de documentation s'affiche. Puis un développeur frontend génère un client à partir de votre spécification, la compilation échoue à cause d'un champ required manquant, et vous découvrez que votre description d'API "terminée" comportait une faute de frappe dans un $ref il y a trois commits. La spécification était incorrecte depuis le début. Rien ne vous l'a dit avant que cela ne coûte une après-midi à quelqu'un.
C'est le travail d'un validateur Swagger : il lit votre fichier OpenAPI ou Swagger et vous indique, avant que quiconque ne l'utilise, si le document est réellement valide. Pas "semble-t-il correct", mais "est-il conforme à la spécification OpenAPI, résout-il chaque référence et décrit-il un schéma auquel un outil peut faire confiance ?" Un validateur transforme les bugs structurels silencieux en erreurs bruyantes, numérotées par ligne, que vous corrigez en quelques secondes au lieu de les déboguer pendant des heures en aval.
Ce qu'un validateur Swagger vérifie réellement
D'abord, la terminologie. "Swagger" et "OpenAPI" décrivent la même chose à différents moments de l'histoire. Le format s'appelait Swagger jusqu'à la version 2.0, puis a été donné à l'initiative OpenAPI et renommé ; les versions 3.0, 3.1 et 3.2 sont toutes OpenAPI. Les gens disent encore "validateur swagger" par habitude, et la plupart des outils acceptent à la fois Swagger 2.0 et OpenAPI 3.x. Si l'historique des versions est flou, la comparaison Swagger vs OpenAPI l'éclaire. Pour les différences entre les versions récentes, voir ce qui a changé dans OpenAPI 3.2 vs 3.1 vs 3.0.
Un vrai validateur effectue trois tâches, dans l'ordre :
- Analyser. Le fichier est-il seulement un YAML ou un JSON valide ? Une tabulation égarée, une clé dupliquée, une parenthèse non fermée, le document ne se charge jamais. C'est l'erreur la moins coûteuse à détecter et la plus embarrassante à livrer.
- Valider la structure. Le document est-il conforme au schéma OpenAPI ? Chaque opération nécessite un objet
responses. Chaque paramètre a besoin d'une valeurin. Un$refdoit pointer vers quelque chose qui existe. C'est là que se cachent la plupart des vrais bugs. - Résoudre les références. Les documents OpenAPI sont remplis de pointeurs
$refqui assemblent des schémas réutilisables. Un validateur les suit tous et échoue si une cible est manquante, circulaire d'une manière interdite par la spécification, ou pointe vers le mauvais fichier.
Réussissez les trois et vous avez un document que n'importe quel outil conforme, générateur de code, serveur de maquette, moteur de rendu de documentation peut lire sans problème. Échouez à l'un d'entre eux et l'échec apparaîtra dans un endroit moins pratique que votre terminal.
Les erreurs qu'il détecte et qui causent des problèmes plus tard
La validation semble abstraite jusqu'à ce que vous voyiez ce qui passe à travers sans elle. Ce sont les erreurs de spécification qui semblent inoffensives dans l'éditeur et se transforment en incidents réels en aval.
Pointeurs $ref cassés. Vous renommez un schéma de User en UserProfile mais oubliez une référence profondément imbriquée dans un corps de réponse. Le YAML s'analyse toujours. La documentation affiche toujours le reste de la page. Le générateur de code tombe sur le pointeur orphelin et génère un client avec un type manquant, ou plante tout simplement. Un validateur signale le $ref cassé au moment où vous enregistrez.
Désaccord entre schéma et exemple. Votre schéma indique que age est un entier ; votre exemple montre "age": "trente". Swagger UI affiche les deux sans problème. Un serveur de maquette construit à partir de la spécification renvoie alors une chaîne de caractères là où les consommateurs attendent un nombre, et un test de contrat à trois équipes de distance passe au rouge pour des raisons que personne ne peut retracer jusqu'à votre fichier.
Éléments requis manquants. Une opération sans responses. Un paramètre de chemin déclaré dans le modèle d'URL mais jamais défini dans parameters. Un requestBody sans content. Chacun est techniquement un document mal formé, et chacun produit un symptôme différent en aval selon l'outil qui lit la spécification en premier.
Dérive de type et de format. format: date-time sur un champ que votre backend renvoie sous forme de timestamp Unix. type: string sur quelque chose qui est en réalité un tableau. Ceux-ci passent la validation structurelle mais rompent le contrat entre la spécification et l'API en cours d'exécution, ce qui est un problème distinct que nous aborderons plus tard.
Le schéma est constant : une erreur de spécification est invisible au moment où vous la commettez et coûteuse au moment où quelqu'un d'autre la consomme. La validation ramène le coût là où il est abordable.
Comment valider un fichier Swagger à la main
Vous n'avez pas besoin d'une plateforme pour commencer. Il existe trois façons rapides de valider une spécification aujourd'hui.
L'éditeur Swagger. Collez votre YAML dans l'éditeur Swagger et il valide au fur et à mesure que vous tapez, soulignant les erreurs avec les numéros de ligne dans la marge droite. C'est le moyen le plus rapide de vérifier la cohérence d'un seul fichier, et c'est gratuit. La limite est que c'est une seule boîte de texte : il valide le document mais ne fait rien pour savoir si votre API réelle correspond toujours, et vous écrivez du YAML à la main sans constructeur de schéma visuel. Pour apprendre le format, c'est bien. Pour une spécification dont dépend une équipe, c'est un onglet dans un flux de travail qui en nécessite plusieurs.
Un linter comme Spectral. Spectral de Stoplight est un CLI open-source qui va au-delà de la validité brute pour inclure des règles de style. Il vérifie la validité structurelle et vous permet d'appliquer un ensemble de règles : chaque opération nécessite une description, chaque propriété de schéma nécessite un type, la nomination suit votre convention. Spectral est véritablement l'outil le meilleur de sa catégorie pour régir le style des spécifications à travers de nombreux fichiers, et si la conception cohérente d'API est votre préoccupation, il vaut la peine de l'adopter. Vous l'exécutez comme ceci :
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Le compromis est la portée. Spectral valide et linter le document. Ce n'est pas un exécuteur de requêtes ; il ne vous dira pas si l'API décrite par la spécification se comporte réellement comme la spécification le prétend. C'est une couche différente, et c'est la couche où se trouvent la plupart des surprises en production.
Un point de terminaison de validation en ligne. Le projet Swagger publie un service de validation qui renvoie un badge de succès ou d'échec pour une URL de spécification hébergée. C'est pratique pour un badge README, moins pour une boucle de correction interactive. Pour une couverture plus approfondie des options autonomes, nous avons une compilation des meilleurs outils de validation OpenAPI et un guide détaillé sur comment valider les spécifications OpenAPI.
Tous les trois valident le document. Aucun d'entre eux ne comble l'écart entre une spécification valide et une API correcte. C'est cet écart que la section suivante aborde.
Où Apidog intervient : valider la spécification, puis prouver que l'API y correspond
Apidog est une plateforme API tout-en-un : vous concevez le schéma, déboguez les requêtes, créez des scénarios de test automatisés, simulez des endpoints et publiez de la documentation dans un seul espace de travail. La validation des spécifications n'est pas un outil séparé que vous ajoutez ; c'est une propriété inhérente au travail au sein de la plateforme.
Lorsque vous importez un fichier Swagger ou OpenAPI, ou en concevez un dans l'éditeur visuel, Apidog l'analyse et le valide dès l'entrée. Un document mal formé, un $ref cassé, un paramètre sans type, tout cela apparaît au fur et à mesure que vous travaillez, et non pas après trois outils en aval. Parce que l'éditeur est visuel, toute une catégorie d'erreurs YAML écrites à la main ne se produit jamais : vous ne pouvez pas oublier la valeur in sur un paramètre lorsque le champ est une liste déroulante requise. La spécification est valide par construction.
Cela gère le document. Le problème le plus difficile est la dérive, le lent désaccord entre une spécification qui dit une chose et une API qui en fait une autre. Un validateur autonome ne peut pas détecter cela, car le fichier est valide ; c'est le service en cours d'exécution qui est incorrect. C'est le mode d'échec derrière tant de documentations Swagger et collections Postman en dérive.
Apidog résout ce problème en faisant de la spécification la source de vérité pour les tests. Vous générez des scénarios de test directement à partir de votre spécification OpenAPI, puis vous affirmez que les réponses réelles correspondent au schéma que vous avez déclaré. Lorsque la spécification indique que age est un entier et que l'API renvoie une chaîne de caractères, le test échoue, et il échoue par rapport à la spécification, et non par rapport à une copie maintenue à la main. La question du validateur devient continue : non pas "ce fichier était-il valide quand je l'ai enregistré" mais "l'API en direct est-elle toujours conforme à son contrat actuellement ?" Si vous voulez les mécanismes d'assertion, les assertions API : un guide pratique couvre la validation de la forme de la réponse, du statut et des champs.
Pour les équipes qui souhaitent que la validation soit appliquée automatiquement plutôt que mémorisée, Apidog couvre également la conformité des API aux normes OpenAPI dans le cadre du cycle de conception.
Exécuter la validation basée sur les spécifications en CI avec l'interface CLI d'Apidog
Un validateur qui ne s'exécute que lorsque quelqu'un ouvre l'éditeur est un validateur qui finit par être ignoré. La solution consiste à intégrer la validation dans le pipeline, où elle s'exécute à chaque push sans intervention humaine. C'est à cela que sert l'exécuteur en ligne de commande Apidog.
L'interface CLI est un package npm nommé apidog-cli. Il exécute les scénarios de test que vous avez créés dans Apidog, sans interface graphique, depuis n'importe quel environnement doté de Node.js. Installez-le avec une seule commande :
npm install -g @apidog/cli
Exécutez ensuite un scénario enregistré, le même scénario qui affirme que vos réponses en direct correspondent à la spécification, contre un environnement :
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Quelques notes sur ce que font ces flags. -t est l'ID du scénario de test. -e est l'ID de l'environnement, vous pouvez donc pointer les mêmes vérifications vers l'environnement de staging lors d'une pull request et vers la production après le déploiement. -r choisit les formats de rapport : cli pour une sortie de journal de compilation lisible, et vous pouvez ajouter html, json ou junit pour alimenter un tableau de bord CI. Le --access-token doit être un secret CI, jamais en ligne. Vous générez à la fois le token et la commande prête à l'emploi depuis l'onglet CI/CD du scénario dans Apidog. Pour la surface de drapeaux complète, exécutez apidog run --help ou lisez le guide complet de l'interface CLI d'Apidog.
Le détail qui en fait une véritable passerelle : l'interface CLI se termine avec un code de statut non nul lorsqu'une assertion échoue. Les systèmes CI lisent ce code de sortie. Une vérification de schéma échouée fait échouer l'étape, ce qui fait échouer la tâche, ce qui bloque la fusion. Ainsi, dès que votre API cesse de correspondre à son contrat OpenAPI, la compilation passe au rouge, avant que le changement ne soit livré, et non après qu'un consommateur ait déposé un ticket. C'est la différence entre valider un fichier une fois et valider le contrat à chaque commit. Le même comportement de code de sortie explique pourquoi l'exécuteur s'intègre à n'importe quelle plateforme CI, un peu comme l'exécution de collections Postman en CI sans Newman.
Téléchargez Apidog si vous voulez la validation des spécifications et le test de contrat au même endroit où votre équipe conçoit déjà l'API.
Un workflow de validation pratique
En assemblant les pièces, voici une séquence qui détecte les erreurs de spécification à chaque étape au lieu de juste la dernière :
- Concevoir ou importer dans un éditeur validateur. Que vous importiez un fichier Swagger existant ou le construisiez dans le concepteur visuel d'Apidog, le document est analysé et validé structurellement dès l'entrée. Les références cassées et les types manquants apparaissent immédiatement.
- Linter pour le style si vous avez un ensemble de règles. Si votre organisation applique des règles de nommage et de description, exécutez Spectral comme une vérification rapide avant le commit. La validité et le style interne sont des préoccupations différentes ; couvrez les deux.
- Générer des tests à partir de la spécification. Transformez le document OpenAPI en scénarios de test afin que vos assertions soient liées à la même définition que vous livrez, et non à une copie séparée qui dériverait.
- Bloquer chaque push avec l'interface CLI. Intégrez
apidog rundans votre pipeline afin qu'un désaccord entre la spécification et la réalité fasse automatiquement échouer la compilation. - Traiter la spécification comme la source de vérité. Lorsque la conception change, les tests pointent vers le même fichier, il n'y a donc rien à synchroniser manuellement.
Les étapes 1 et 2 valident le document. Les étapes 3 à 5 valident le contrat. Vous avez besoin des deux, et l'endroit le moins coûteux pour les réaliser tous est un seul espace de travail plutôt que quatre onglets de navigateur.
La version courte
Un validateur Swagger détecte les bugs structurels, les références cassées, les types manquants, le YAML mal formé, qui sont invisibles lorsque vous les écrivez et coûteux lorsque quelqu'un d'autre les lit. Valider le document est le minimum, pas le maximum. Les erreurs qui atteignent réellement la production sont celles où une spécification valide cesse discrètement de correspondre à une API en mutation, et aucun validateur de fichier ne peut les voir.
La solution consiste à valider en deux couches et à les regrouper au même endroit : valider le document au fur et à mesure que vous le concevez, puis valider le contrat à chaque push en affirmant que les réponses réelles correspondent à la spécification. Apidog effectue la première par construction et la seconde via des scénarios que l'exécuteur apidog-cli intègre en CI. La spécification reste la source de vérité, la compilation passe au rouge dès que la réalité s'en éloigne, et un fichier Swagger cassé cesse d'être quelque chose que vous découvrez une après-midi trop tard.