Validation du spécification OpenAPI Gérez les erreurs dans votre fichier Swagger avant que les clients ne soient affectés

Un spécification OpenAPI est un contrat entre votre API et tout ce qui la consomme — des clients générés automatiquement, des serveurs de simulation, des documents de documentation et des frameworks de tests. Le problème est que, contrairement au code d'application, une spécification corrompue ne lance pas d'exception. Elle produit silencieusement des sorties incorrectes en aval, et la première fois que vous en entendez parler, c'est lorsque le SDK client génère du code inutilisable ou que vos documents de documentation affichent des points d'accès manquants.

Identifier les erreurs de spécification tôt — avant qu'elles ne parviennent aux consommateurs — est la fonction de la validation de spécification. Cet article explique ce qui doit être validé, où se cachent les erreurs courantes, et comment exécuter la validation localement et dans le navigateur.

Pourquoi la forme de votre spécification importe-t-elle au-delà de la documentation

La plupart des développeurs considèrent une spécification OpenAPI comme un artefact de documentation — quelque chose qui alimente Swagger UI ou Redoc. C'est seulement la moitié de la vérité. La spécification est également la source de vérité pour :

• La génération de code — Des outils comme openapi-generator et swagger-codegen produisent directement des stubs de serveur et des bibliothèques de clients à partir de la spécification. Un schéma mal formé produit du code mal formé.
• Les tests de contrat — Des frameworks comme Dredd et Schemathesis testent votre API en direct contre sa spécification. Une spécification invalide signifie que les tests ne peuvent pas s'exécuter ou produisent des résultats faux.
• Les serveurs de simulation — Des outils comme Prism et des outils similaires servent des réponses simulées basées sur les valeurs d'exemple et les schémas de votre spécification. Des schémas erronés produisent des simulations erronées.
• La configuration du gateway — AWS API Gateway, Kong et d'autres peuvent importer des spécifications OpenAPI pour configurer le routage, l'authentification et la validation. Une spécification invalide supprime silencieusement ou configure mal les routes.

Aucun de ces outils ne vous informe de manière lisible que la spécification est erronée. Ils se crashent, produisent du déchet ou ignorent silencieusement la partie concernée. Valider votre spécification avant qu'elle ne parvienne à ces consommateurs est incontournable.

OpenAPI 2.0 vs 3.0 vs 3.1 : Les différences de version qui piègent les développeurs

La version que vous déclarez au début de votre spécification détermine les règles applicables — et de nombreuses erreurs proviennent de la confusion entre les conventions des différentes versions.

• OpenAPI 2.0 (Swagger) — Utilise swagger: "2.0". Les corps de requête sont placés dans parameters avec in: body. Les définitions sont placées dans definitions, et non pas components/schemas. Aucun support pour oneOf, anyOf, ou not au niveau du schéma.
• OpenAPI 3.0.x — Utilise openapi: "3.0.x". Les corps de requête passent à requestBody. Les schémas se regroupent sous components. Supporte oneOf, anyOf, allOfet not. Ajoute links et callbacks.
• OpenAPI 3.1.0 — S'aligne pleinement sur le JSON Schema draft 2020-12. nullable est remplacée par type: [string, null]. exclusiveMinimum/exclusiveMaximum le changement de booléens en nombres. $schema est maintenant autorisée dans les schémas.

L'erreur de migration la plus courante : copier une spécification 2.0 et modifier le champ de version en 3.0.0 sans déplacer les corps de requête de parameters à requestBody. La spécification semble valide au format JSON/YAML mais échoue à la validation sémantique.

Les erreurs courantes dans les spécifications et où elles se cachent

Les erreurs de spécification suivent des modèles prévisibles. Voici les plus fréquents dans les bases de code réelles :

Champs requis manquants

Chaque opération doit avoir au moins une réponse 2xx définie. Chaque paramètre a besoin d'une name et d'une in valeur. Les paramètres de chemin déclarés dans l'URL (par exemple, /users/{id}) doivent avoir un objet de paramètre correspondant avec in: path et required: true. Manquer l'un de ces éléments produit une spécification techniquement parsable qui fait échouer les validateurs et les générateurs de code en aval.

Chemins $ref invalides

UN $ref qui pointent vers un composant inexistante est l'une des erreurs de spécification les plus courantes. Le référentiel semble valide — $ref: "#/components/schemas/UserProfile" — mais le schéma cible a été renommé ou supprimé. Les parsers JSON/YAML acceptent cela sans remarquer. Seul un validateur de spécification identifie cette erreur.

Chemins externes $ref sont encore plus risqués — ils pointent vers d'autres fichiers ou URLs qui peuvent ne pas être accessibles dans chaque environnement. Insérez ces références directement avant de distribuer votre spécification ou de l'utiliser avec des outils qui ne résolvent pas les externes.

Types de schéma incorrects

Les incohérences de type de schéma sont subtiles. Déclarer type: integer sur un champ qui retourne des valeurs de type float. Utiliser format: date-time avec un champ qui retourne des timestamps Unix (entiers). Définir un enum avec des valeurs qui ne correspondent pas au déclaré type. Ces erreurs passent la validation YAML mais produisent des propriétés mal typées dans les clients générés.

Références circulaires

Un schéma qui se réfère à lui-même — directement ou à travers une chaîne de $ref valeurs — fait planter les générateurs de code et les outils de documentation. La plupart des validateurs détectent et signalent les références circulaires, mais elles peuvent être difficiles à dénouer dans des schémas profondément imbriqués. La solution est généralement de briser le cycle avec un schéma dédié pour le cas récursif.

Erreurs structurelles vs erreurs sémantiques

Les erreurs de validation ne sont pas toutes les mêmes. Comprendre la différence vous aide à prioriser les corrections :

• Erreurs structurelles — La spécification ne respecte pas le schéma OpenAPI. Des champs obligatoires sont manquants, les noms de propriétés sont erronés ou les types ne correspondent pas au format de la spécification. Ces erreurs sont détectées par la validation stricte du schéma et bloquent la plupart des outils.
• Erreurs sémantiques — La spécification est structuellement valide au format JSON/YAML et passe la validation du schéma, mais elle décrit quelque chose qui ne peut pas fonctionner. Un point d'accès avec un paramètre de chemin dans l'URL mais sans définition de paramètre. Un schéma de réponse utilisant allOf avec des champs obligatoires en conflit. Ces erreurs sont détectées par des règles de vérification approfondies, pas par les vérifications de base du schéma.

La plupart des validateurs en ligne et des outils de ligne de commande simples détectent les erreurs structurelles. Pour détecter les erreurs sémantiques, il faut un linter basé sur des règles comme Spectral, qui évalue la logique et la cohérence internes de la spécification.

components/schemas : Définitions partagées vs schémas inline

OpenAPI 3.0 a introduit components/schemas comme lieu canonique pour définir des schémas réutilisables. Le compromis :

• — Correctes lorsque le même schéma apparaît plusieurs fois (par exemple, un — Corriger lorsque le même schéma apparaît plusieurs fois (par exemple un User objet retourné par plusieurs points d'accès). L'utilisation de $ref: "#/components/schemas/User" garantit que la spécification soit DRY et génère une seule classe nommée dans les SDK clients.
• Schémas inline — Corrects pour des formes de réponse uniques, spécifiques à un seul point d'accès et ne seront pas réutilisées. L'inline évite de polluer components/schemas avec des définitions d'usage unique qui rendent la spécification plus difficile à lire.

L'anti-pattern est de définir un schéma dans components/schemas et de ne jamais le référencer. Des validateurs comme Spectral peuvent signaler des composants inutilisés, ce qui indique souvent une $ref qui devait le référencer mais pointe ailleurs.

requestBody vs parameters : Où les choses se mal passent

Dans OpenAPI 3.0, les corps de requête et les paramètres sont strictement séparés :

• parameters — Pour les valeurs de chemin, de requête, d'en-tête et de cookie. Chaque paramètre est une valeur scalaire, pas un objet complexe.
• requestBody — Pour le corps de la requête (corps JSON, données de formulaire, téléchargements de fichiers). Obligatoire pour les opérations POST/PUT/PATCH qui acceptent un corps.

L'erreur qui piège les développeurs lors de la migration de 2.0 : dans Swagger 2.0, les corps de requête étaient des paramètres avec in: body. Dans OpenAPI 3.0, cela est invalide — in: body n'existe pas. Une spécification avec in: body passe la validation YAML mais échoue à la validation de spécification, et les générateurs de code échouent soit ou suppriment silencieusement le corps de requête.

Comment valider votre spécification localement

Trois outils solides de ligne de commande pour la validation locale, de la plus simple à la plus complète :

swagger-cli

Validation structurelle rapide et $ref résolution. Bonne pour un contrôle rapide :

npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

Signale les erreurs structurelles et les chemins brisés. $ref Ne détecte pas les problèmes sémantiques ni les problèmes de style.

Redocly CLI

Validation structurelle plus un ensemble de règles configurable. Bonne rigidité par défaut pour les spécifications de production :

npm install -g @redocly/cli
redocly lint openapi.yaml

Détecte les descriptions manquantes, les références brisées et de nombreuses erreurs sémantiques par défaut.

Spectral

Le linter le plus configurable. Exécute l'ensemble des règles OpenAPI par défaut plus des règles que vous définissez. Idéal pour les équipes qui veulent imposer des directives internes sur la style de l'API :

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Spectral distingue les erreurs (bloquantes) des avertissements (problèmes de style ou de complétude), afin que vous puissiez corriger d'abord les problèmes bloquants sans être submergé par les règles de conseil.

Valider dans votre navigateur sans installer quoi que ce soit

Si vous voulez valider une spécification rapidement — sans configurer une ligne de commande ni exécuter une build — le Validateur de spécification OpenAPI / Swagger sur iotools.cloud fonctionne entièrement dans le navigateur. Collez votre spécification YAML ou JSON et il signale les erreurs structurelles, les chemins brisés, les champs requis manquants et les problèmes spécifiques à chaque version d'OpenAPI 2.0, 3.0 et 3.1. $ref C'est utile pour un contrôle rapide avant de commiter, pour examiner une spécification envoyée par quelqu'un d'autre, ou pour valider une spécification générée à partir d'annotations avant de lancer la génération de code.

Intégrer la validation dans votre flux de travail

Une validation ponctuelle détecte des problèmes immédiats, mais ne prévient pas les régressions. Une approche plus durable :

Hook avant chaque commit

• — Exécute avant chaque commit. Une spécification corrompue ne parvient jamais au dépôt. swagger-cli validate ou spectral lint Étape du pipeline CI
• — Ajoutez la validation de spécification comme étape précoce dans votre pipeline CI, avant toute étape de génération de code ou de déploiement qui dépend de la spécification. Validation de la spécification générée
• — Si vous générez votre spécification à partir d'annotations de code (par exemple, springdoc, swagger-annotations, FastAPI), validez le résultat généré, et non seulement les annotations. La génération elle-même peut produire un résultat invalide lorsque les annotations sont en conflit ou incomplètes. L'objectif est de rendre impossible l'envoi d'une spécification invalide — et non simplement de la corriger lorsque un consommateur en signale un problème.

L'objectif est de rendre un spécificateur invalide impossible à livrer — pas simplement quelque chose que vous corrigez lorsque un consommateur signale un problème.

Vous aimerez peut-être aussi