Validateur OpenAPI et Swagger

Une description OpenAPI sert de contrat entre les personnes qui développent, documentent et consomment une API. Une indentation YAML incorrecte, un champ obligatoire absent ou une référence introuvable peuvent empêcher son exploitation. Ce validateur aide à repérer ces erreurs dans un fichier JSON ou YAML, directement dans le navigateur. Il accepte Swagger 2.0, OpenAPI 3.0.0 à 3.0.4 et OpenAPI 3.1.0 à 3.1.2, avec le périmètre de contrôle indiqué dans le rapport.

La vérification commence par la syntaxe : le texte doit pouvoir être lu comme un document JSON ou YAML unique, sans clés répétées. Elle vérifie ensuite la version et la structure attendue, notamment les informations de l’API et les opérations décrites. Un fichier syntaxiquement correct peut donc rester non conforme au schéma OpenAPI de sa version.

Les références internes utilisent des JSON Pointers, par exemple #/components/responses/Ok. Elles désignent un emplacement dans le même document. Le validateur vérifie leur résolution et distingue les véritables références des clés $ref contenues dans les données d’un exemple. Les liens vers d’autres fichiers ou vers des schémas distants sont refusés : aucun résolveur ne les télécharge.

Des contrôles complémentaires portent sur les identifiants operationId des routes et webhooks, les paramètres des chemins et les types des mots-clés des schémas 3.1. Une réussite reste partielle : elle ne vérifie pas toutes les contraintes sémantiques, les formats ou la conformité des exemples. Les dialectes personnalisés, $id, ancres et références dynamiques sont signalés comme hors périmètre.

Un chemin de diagnostic tel que /paths/~1health/get/responses désigne le champ responses de GET /health : dans un JSON Pointer, ~1 représente une barre oblique. La ligne est affichée lorsqu’elle peut être retrouvée dans le texte source. Commencez par la première cause claire avant de traiter les erreurs secondaires produites par un même objet incomplet.