Validateur OpenAPI 3.1

Ce que fait cet outil avec les fichiers 3.1

La version 3.1 aligne les schémas sur JSON Schema 2020-12. Ce validateur n’examine pas l’intérieur des schémas. Il inspecte uniquement le premier niveau et les entrées de chemins, donc les fonctions de schéma de la 3.1, comme les tableaux de types ou const, ne réussissent ni n’échouent ici. La valeur de la version elle-même n’est pas contrôlée : tout champ openapi est considéré comme présent.

Deux motifs 3.1 à surveiller

OpenAPI 3.1 permet de ne décrire que des webhooks et de omettre paths. Cet outil exige paths : un tel fichier est donc signalé par une erreur, même si la spécification l’autorise. Ajouter un objet paths: {} vide satisfait le contrôle.

La liste des méthodes utilisée ici comprend get, post, put, patch, delete, head, options, ainsi que parameters, summary, description et servers. La méthode trace existe dans la spécification, mais elle ne figure pas dans cette liste : elle déclenche donc un avertissement que vous pouvez ignorer si elle est volontaire. Les avertissements ne rendent pas le document invalide.

Un exemple concret

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

Résultat : une erreur, « Objet ‘paths’ manquant. » Ajoutez paths: {} et la structure est acceptée.

Quand s’en tenir là et quand aller plus loin

Utilisez cette page pour confirmer qu’un fichier 3.1 a la bonne forme avant d’ouvrir une pull request ou de le partager avec un partenaire. Les contrôles sont rapides et les messages sont clairs. Une fois la structure correcte, les règles de schéma 3.1 nécessitent encore un linter complet, car c’est là que se cachent la plupart des vraies erreurs : déclarations de types invalides, références cassées et définitions de réponses manquantes. Considérez ces deux étapes comme complémentaires, et non comme des alternatives.

Si un avertissement est volontaire, comme trace, notez-le dans votre pull request pour que les relecteurs ne s’interrogent pas. Les avertissements ne modifient jamais le résultat valide : vous pouvez les conserver sans risque. Les erreurs sont les points à résoudre avant de partager le fichier.