Une spécification OpenAPI est un contrat. Les générateurs de code la lisent, la documentation en est tirée, les serveurs de maquette l'exécutent et les SDK clients en sont produits. Lorsque la spécification est erronée, chacun de ces artefacts en aval hérite de l'erreur. Un validateur détecte le problème dans le fichier de spécification avant qu'il ne se propage.
Cet aperçu couvre les outils de validation OpenAPI qui valent la peine d'être utilisés, ce à quoi chacun est bon et comment ils s'intègrent dans un véritable flux de travail. Certains vérifient la syntaxe brute. D'autres appliquent des règles de style et de conception. La meilleure configuration combine généralement les deux, et ce guide explique comment l'assembler.
Pourquoi la validation de la spécification est importante
Un validateur résout deux problèmes distincts, et les confondre crée de la confusion.
Le premier est l'exactitude. Le fichier est-il une spécification OpenAPI valide ? Un bloc YAML mal indenté, une référence `ref` qui ne pointe nulle part, une réponse à laquelle il manque sa `description` requise, un schéma avec une faute de frappe dans un nom de type. Ce sont des erreurs objectives. Le fichier est soit conforme au schéma OpenAPI, soit il ne l'est pas. Un validateur d'exactitude vous donne une réponse oui ou non.
Le second est la qualité. La spécification est valide, mais est-elle bonne ? Chaque opération devrait avoir un résumé. Les noms de chemins devraient être cohérents. Chaque réponse d'erreur devrait être documentée. La sécurité devrait être déclarée. Aucune de ces exigences n'est imposée par le schéma OpenAPI, mais les ignorer produit une spécification techniquement valide mais difficile à consommer. Un linter applique ces règles de conception. Détecter ces deux catégories de problèmes tôt est bien moins coûteux que de les détecter après l'expédition d'un SDK, ce qui est la même logique derrière les tests de contrat d'API plus largement.
Les outils de validation à connaître
Swagger Editor
Swagger Editor est l'éditeur officiel basé sur le navigateur du projet OpenAPI. Vous collez ou écrivez votre spécification à gauche et voyez les erreurs de validation et un aperçu rendu à droite, en direct. C'est le moyen le plus rapide de vérifier si une spécification est syntaxiquement valide, sans aucune configuration. Il est excellent pour l'édition et les vérifications rapides, moins adapté aux exécutions automatisées en pipeline. Le Swagger Editor est gratuit et s'exécute entièrement dans le navigateur.
Spectral
Spectral, de Stoplight, est le linter que la plupart des équipes adoptent pour l'application de la qualité. Il propose des ensembles de règles pour OpenAPI et AsyncAPI, et sa véritable valeur réside dans les règles personnalisées. Vous écrivez des règles en YAML ou JavaScript pour appliquer vos propres conventions, comme exiger que chaque opération ait une description ou interdire les barres obliques finales dans les chemins. Il s'exécute depuis la ligne de commande, ce qui en fait un ajustement naturel pour l'intégration continue (CI). Le projet Spectral est open source.
openapi-spec-validator
openapi-spec-validator est un outil Python ciblé qui fait bien une seule chose : il vérifie une spécification par rapport au schéma OpenAPI officiel pour les versions 2.0, 3.0 et 3.1. Il n'a pas d'opinion sur le style. Il vous dit si le fichier est structurellement correct. En tant que bibliothèque ou CLI, il s'intègre parfaitement dans les étapes de construction basées sur Python et les hooks de pré-validation. Lorsque vous voulez un contrôle strict de conformité, c'est un choix clair.
Apidog
Apidog valide la spécification dans le cadre d'un flux de travail de conception intégré. Lorsque vous construisez ou importez une définition OpenAPI, il signale les problèmes structurels dans l'éditeur. Sa fonctionnalité la plus distinctive est la validation d'exécution : il vérifie les réponses d'API en direct par rapport au schéma déclaré dans votre spécification, de sorte que vous détectez les dérives où l'implémentation ne correspond plus au contrat. Cela comble l'écart entre un document valide et une API correcte. Téléchargez Apidog pour concevoir et valider des spécifications dans un seul outil.
Redocly CLI
Redocly CLI regroupe le linting, la validation et la génération de documentation. Il valide par rapport au schéma OpenAPI, propose un ensemble de règles configurable et peut résoudre des spécifications multi-fichiers en un seul bundle. Les équipes qui rendent déjà des documents avec Redoc obtiennent la validation dans la même chaîne d'outils sans ajouter de dépendance supplémentaire.
Vacuum
Vacuum est un linter OpenAPI rapide écrit en Go. Son atout est la vitesse sur de très grandes spécifications, où certains linters basés sur JavaScript ralentissent. Il est compatible avec les règles de style Spectral, de sorte qu'une équipe peut passer à Vacuum avec peu de retravail. Pour un monorepo avec une surface d'API étendue, la différence de performance est notable.
Tableau comparatif
| Outil | Type | Vérifications | Fonctionne en CI | Idéal pour |
|---|---|---|---|---|
| Swagger Editor | Éditeur navigateur | Syntaxe, schéma | Non | Édition en direct et vérifications rapides |
| Spectral | Linter CLI | Style, règles personnalisées | Oui | Application des conventions de conception |
| openapi-spec-validator | CLI / Bibliothèque Python | Exactitude du schéma | Oui | Porte stricte de validation (succès/échec) |
| Apidog | Plateforme intégrée | Schéma + dérive d'exécution | Oui | Conception et validation des réponses |
| Redocly CLI | CLI | Schéma, style, regroupement | Oui | Docs et validation ensemble |
| Vacuum | Linter CLI | Style, règles Spectral | Oui | Très grandes spécifications, vitesse |
Comment assembler un flux de travail de validation
Vous ne choisissez pas un seul outil. Vous les superposez.
Commencez là où vous éditez. Pendant l'écriture d'une spécification, utilisez Swagger Editor ou une plateforme intégrée afin que les erreurs apparaissent au fur et à mesure que vous tapez. Cela permet de détecter les erreurs évidentes immédiatement et est beaucoup moins coûteux que de les détecter plus tard.
Ajoutez une porte de validation de l'exactitude dans la CI. Exécutez openapi-spec-validator ou un équivalent CLI sur chaque demande de tirage (pull request) qui touche la spécification. Si le fichier n'est pas validé par rapport au schéma OpenAPI, la construction échoue. C'est non négociable et binaire.
Ajoutez une porte de qualité juste à côté. Exécutez Spectral, ou Vacuum sur les grandes spécifications, avec un ensemble de règles sur lequel votre équipe est d'accord. Commencez par les règles OpenAPI intégrées, puis ajoutez des règles personnalisées pour vos propres conventions. Conservez l'ensemble de règles sous contrôle de version afin qu'il évolue avec l'API. C'est la même discipline qui rend fiable l'automatisation des tests en CI/CD : la vérification s'exécute à chaque fois, pas seulement quand quelqu'un s'en souvient.
Enfin, validez l'API en cours d'exécution par rapport à la spécification. Une spécification peut être parfaite tandis que l'implémentation s'en est éloignée. La validation d'exécution, que ce soit via Apidog ou des tests de contrat dans votre suite, confirme que l'API correspond toujours à son contrat. Pour la partie test, écrire des assertions d'API utiles explique comment vérifier les réponses par rapport au schéma documenté.
Une erreur courante : ne valider qu'une seule fois
De nombreuses équipes valident une spécification une fois, lors de sa première rédaction, puis plus jamais. La spécification se dégrade à partir de là. Un développeur ajoute un endpoint dans le code et oublie la spécification. Quelqu'un modifie la forme d'une réponse. Six mois plus tard, la spécification décrit une API qui n'existe plus, et les SDK et les documents générés sont silencieusement erronés.
La validation doit être continue. Intégrez-la à la CI afin que chaque modification de la spécification soit vérifiée, et chaque modification de l'API soit vérifiée par rapport à la spécification. Traitez un échec de spécification de la même manière qu'un échec de test unitaire : la construction ne passe pas. Le principe est le même que celui derrière les tests automatisés en général, à savoir qu'une vérification n'a de valeur que si elle s'exécute sans que personne ne décide de l'exécuter.
Il est également utile de valider par rapport à la bonne version d'OpenAPI. La version 3.1 a aligné OpenAPI avec JSON Schema, ce qui a modifié le comportement de certaines constructions de schéma. Si vos outils supposent la version 3.0 mais que votre spécification déclare la version 3.1, vous pouvez obtenir des résultats trompeurs. La spécification OpenAPI officielle documente les différences de version, et la plupart des validateurs vous permettent de fixer explicitement la version.
Ce que les validateurs détectent et que vous manqueriez
Il est utile d'être concret sur les types de problèmes que la validation met en évidence, car « la spécification est erronée » est trop vague pour agir.
Les erreurs structurelles sont les plus faciles à visualiser. Une `ref` qui pointe vers un schéma qui n'existe pas. Un objet de réponse sans `description`, ce qu'OpenAPI exige. Un paramètre de chemin déclaré dans le modèle d'URL mais jamais défini dans la liste `parameters`. Un schéma qui indique `type: integer` alors que l'exemple montre une chaîne de caractères. Un validateur d'exactitude signale chacun de ces problèmes, et chacun d'eux casserait un générateur de code ou produirait un SDK défectueux.
Les problèmes de qualité sont plus subtils et plus courants. Une opération sans `operationId`, ce qui rend les noms de méthodes client générés laids ou instables. Une casse de chemin incohérente, où certaines routes utilisent `snake_case` et d'autres `camelCase`. Des points de terminaison qui documentent une réponse 200 mais jamais une 400 ou 401, de sorte que les consommateurs n'ont aucune idée de l'apparence des erreurs. Un corps de requête marqué comme facultatif alors que l'API l'exige réellement. Aucune de ces erreurs ne casse un analyseur, mais toutes rendent l'API plus difficile à utiliser, et un linter est ce qui maintient la ligne. Le lien avec le comportement réel est ce que le test de contrat d'API vérifie une fois que la spécification elle-même est propre.
Intégrer la validation dans un flux de travail axé sur la conception
De nombreuses équipes conçoivent désormais l'API avant d'écrire le code, produisant d'abord la spécification OpenAPI et générant des stubs de serveur, des maquettes et des documents à partir de celle-ci. La validation est encore plus importante dans ce modèle, car la spécification n'est pas la documentation d'une API existante ; c'est la source de vérité à partir de laquelle tout le reste est construit. Une faille dans la spécification devient une faille dans le serveur généré.
Dans un flux axé sur la conception, validez au moment de la conception. Les vérifications au niveau de l'éditeur détectent les erreurs au fur et à mesure que la spécification prend forme, avant toute exécution de génération de code. Ensuite, les portes de la CI confirment que rien n'a régressé. Parce que la spécification pilote également le serveur de maquette, une spécification propre signifie que la maquette se comporte correctement, ce qui permet aux équipes front-end et client de construire sur une base fiable. Si vous voulez voir comment une spécification alimente la maquette, notre guide sur la simulation d'une API pour les tests montre le lien. La discipline est rentable : chaque heure passée à maintenir la spécification valide économise plusieurs heures de débogage de clients non concordants plus tard.
Questions fréquemment posées
Quelle est la différence entre un validateur OpenAPI et un linter ?
Un validateur vérifie si la spécification est structurellement correcte par rapport au schéma OpenAPI, en donnant une réponse de succès ou d'échec. Un linter vérifie la qualité et le style, par exemple si chaque opération a une description ou si la nomination des chemins est cohérente. De nombreux outils font les deux, mais ils répondent à des questions différentes, et un flux de travail solide utilise les deux.
Puis-je valider une spécification OpenAPI gratuitement ?
Oui. Swagger Editor, Spectral, openapi-spec-validator, Redocly CLI et Vacuum sont tous gratuits et open source. Apidog valide les spécifications sur son niveau gratuit et ajoute des vérifications d'exécution. Il n'y a aucune raison de sauter la validation pour des raisons de coût.
Devrais-je valider OpenAPI 3.0 et 3.1 différemment ?
Vous les validez avec les mêmes outils, mais vous fixez la version. OpenAPI 3.1 s'est aligné sur JSON Schema et a modifié certains comportements de schéma, de sorte qu'un validateur s'attendant à la version 3.0 peut signaler de fausses erreurs sur une spécification 3.1. Assurez-vous que vos outils supportent la version que votre spécification déclare.
Où la validation de la spécification doit-elle s'exécuter ?
À deux endroits. En direct dans votre éditeur lors de la rédaction de la spécification, afin que les erreurs apparaissent immédiatement, et dans la CI sur chaque demande de tirage, afin que rien ne soit fusionné avec une spécification cassée ou de mauvaise qualité. La validation uniquement dans l'éditeur est facile à ignorer ; la validation CI ne l'est pas.
Comment puis-je vérifier que mon API correspond à sa spécification ?
La validation de la spécification ne confirme que la correction du document, pas que l'implémentation y correspond. Pour détecter la dérive, exécutez des tests de contrat ou une validation d'exécution qui compare les réponses d'API en direct au schéma de la spécification. Apidog le fait directement, et les frameworks de test de contrat le font dans une suite de tests.