Validateur OpenAPI

À propos du Validateur OpenAPI

La plupart des équipes génèrent ou écrivent à la main un document OpenAPI, puis ne le passent jamais dans un linter jusqu'à ce qu'un SDK client casse en production. Cet outil vous donne une première revue rapide, entièrement dans le navigateur : collez votre spec OpenAPI 3.0 ou 3.1 en JSON ou YAML, ou téléversez votre fichier openapi.yaml / openapi.json, pour obtenir une vérification structurelle, un résumé endpoint par endpoint et une liste priorisée des problèmes courants — operationIds manquants, paramètres de chemin non déclarés (y compris les paramètres partagés au niveau du path item), réponses 401/403 manquantes sur les endpoints authentifiés, opérations d'écriture sans réponse 400/422 de validation, objets de réponse sans description et request bodies sans exemples.

L'outil parcourt aussi chaque $ref du document et signale comme erreur les références locales non résolues (un #/components/schemas/Foo pendant) ainsi que les refs externes/distantes qu'il ne peut pas télécharger hors-ligne — la plus grande cause de plantages des générateurs de code et d'opérations supprimées en silence. Trois niveaux de rigueur pour vous concentrer sur l'essentiel selon la maturité de votre API : Basique pour les brouillons, Recommandée pour la revue de production et Stricte pour les specs prêtes pour SDK. Aucune spec ne sort de votre navigateur.

Comment valider un fichier OpenAPI ou Swagger en ligne ?

Trois étapes, le tout dans votre navigateur. (1) Collez votre document OpenAPI 3.0 ou 3.1 dans la zone en JSON ou YAML, ou téléversez votre fichier openapi.yaml, openapi.yml ou openapi.json avec le bouton de fichier au-dessus de la zone de texte. (2) Choisissez un niveau de rigueur — Basique pour les brouillons, Recommandée pour la revue de production, Stricte pour les specs prêtes pour SDK — et activez les vérifications de réponses auth et d'exemples à votre convenance. (3) Cliquez sur Valider la spec. Vous obtenez immédiatement un résumé réussi/échoué, quatre statistiques (paths, opérations, schémas, refs résolues), un tableau d'endpoints avec méthodes et indicateurs d'auth, et une liste de problèmes triée par sévérité (ERREUR / AVERT. / INFO). Rien n'est envoyé à un serveur — l'analyse et le lint s'exécutent entièrement sur votre machine, donc c'est sûr pour les API privées et internes.

Comment l'outil détecte-t-il les références $ref cassées ou non résolues ?

Il parcourt tout le document analysé, collecte chaque pointeur "$ref" et résout chacun. Les pointeurs locaux comme #/components/schemas/Pet sont résolus contre la spec selon les règles de JSON-pointer (y compris le déséchappement ~1 → / et ~0 → ~) ; si le composant cible n'existe pas, la ref est signalée en ERREUR — c'est la cause nº1 de plantage ou de suppression silencieuse d'opérations par openapi-generator, oapi-codegen, Kiota, openapi-typescript et Redocly. Les refs externes ou distantes (URLs http(s)://, ou chemins de fichier comme ./common.yaml#/Address) sont signalées en AVERT. car cet outil hors-ligne ne peut pas les télécharger et les vérifier — résolvez-les en CI avec Spectral, Redocly CLI ou vacuum. La statistique 'Refs résolues' indique combien de références locales pointaient vers un composant réel, pour confirmer d'un coup d'œil que votre graphe de composants est intact. Coupables fréquents d'une ref pendante : une faute de frappe dans le nom du composant, un schéma que vous avez renommé mais oublié de mettre à jour, ou un $ref vers un chemin qui vit dans un autre fichier non encore empaqueté.

L'outil valide-t-il selon le JSON Schema complet d'OpenAPI 3.1 ?

Pas totalement — il implémente un sous-ensemble pragmatique centré sur les problèmes qui causent réellement des échecs de génération de SDK, de la documentation cassée et des failles de sécurité en production. Nous vérifions les champs racines requis (version openapi, info.title, info.version), les déclarations de paramètres de chemin, la casse des méthodes HTTP, la couverture des codes de réponse, la structure du request body pour les opérations d'écriture et la corrélation sécurité/réponses. Pour une validation complète selon le meta-schéma officiel, exécutez en CI des outils comme Spectral, Redocly CLI ou vacuum après cette passe navigateur — ils téléchargent le JSON Schema et appliquent des milliers de règles. L'outil navigateur est votre revue quotidienne ; le CI est votre porte.

Pourquoi 401 et 403 sont signalées comme manquantes alors que mon endpoint exige clairement l'authentification ?

Parce que les clients, générateurs de SDK et explorateurs d'API ont besoin de formes de réponse explicites pour gérer les erreurs correctement. Déclarer `security: [{bearerAuth: []}]` indique que l'authentification est requise, mais si vous ne documentez que `200: OK`, le SDK généré n'a aucune forme typée pour le corps 401 — donc à l'expiration du token, le client lance une erreur de parsing opaque au lieu d'un AuthError typé. Ajoutez au moins `401: { description: Token invalide ou manquant }` et idéalement un schéma avec champs `code` et `message`. Pour les endpoints à rôles (POST/PUT/DELETE/PATCH), ajoutez aussi 403 Forbidden pour distinguer 'non authentifié' de 'mauvaise permission'. Désactivez la vérification si vous gérez les erreurs d'auth uniformément dans une gateway.

Quelle est la différence entre OpenAPI 3.0 et 3.1 et ce validateur gère-t-il les deux ?

OpenAPI 3.1 aligne le vocabulaire avec JSON Schema 2020-12 : `nullable: true` est remplacé par `type: [string, null]`, `exclusiveMinimum/Maximum` deviennent des nombres au lieu de booléens, `example` devient `examples` (tableau), les webhooks deviennent de première classe et `$ref` peut coexister avec des keywords frères. Le validateur détecte 3.0.x ou 3.1.x via le champ `openapi` et applique les mêmes vérifications structurelles (les règles de lint se chevauchent largement). Si vous mélangez les conventions — comme `nullable: true` dans une spec `openapi: 3.1.0` — la plupart des outils tolèrent mais la sortie du SDK peut surprendre. Pour les repos multi-versions, fixez une version majeure par projet.

Pourquoi le parser YAML échoue sur certaines specs alors que la version JSON fonctionne ?

Nous livrons un parser YAML délibérément petit (pas d'anchors, pas de merge keys `<<`, pas de tags `!!type`, pas de streams multi-documents `---`) pour garder l'outil hors-ligne et léger. ~95 % des specs réelles testées parsent bien, mais les specs chargées en anchors YAML (courantes pour dédupliquer les formes de réponse partagées) échoueront. Deux solutions : (1) exportez YAML vers JSON avec `npx js-yaml spec.yaml > spec.json` — l'expansion des anchors a lieu à la conversion ; (2) inlinez les anchors manuellement. Le message d'erreur indiquera la ligne. Pour un support YAML complet, utilisez Spectral ou Redocly CLI sur desktop qui utilisent js-yaml complet.

Que signifie 'paramètre de chemin non déclaré' et pourquoi cela casse les clients ?

Quand votre template de chemin inclut `{petId}` (ou tout autre `{name}`), chaque placeholder doit apparaître dans la liste `parameters` de l'opération avec `in: path` et `required: true`. Si `{petId}` est dans l'URL mais absent de parameters, les générateurs comme openapi-generator, oapi-codegen, Kiota et openapi-typescript ne peuvent produire d'argument typé — ils sautent l'opération, émettent une méthode sans argument avec `{petId}` littéral dans l'URL ou plantent. Le validateur trouve les deux directions : paramètres dans l'URL mais non déclarés, et déclarés mais absents du chemin. Corrigez en ajoutant les déclarations manquantes ou en supprimant les obsolètes — l'URL est la source de vérité.

Chaque opération doit-elle avoir un operationId unique et quelle convention de nommage est la meilleure ?

Oui — les générateurs utilisent operationId comme nom de méthode dans les SDK clients. Sans lui, ils en synthétisent un à partir de méthode + chemin, produisant des noms laids et instables comme `getPetsPetId`. Convention : verbe + ressource + qualificatif, camelCase : `listPets`, `getPet`, `createPet`, `updatePet`, `deletePet`, `searchPets`, `getPetVaccinations`. Gardez les operationIds globalement uniques (certains générateurs utilisent un namespace par tag, beaucoup non). Pour les listes paginées, préférez `listPets` à `getPets` pour signaler la multiplicité. Pour les endpoints batch, utilisez `bulkCreatePets`. Le validateur signale les operationIds manquants en WARN — corrigez avant qu'un client externe ne consomme votre spec.

Ce validateur convient-il aux specs OpenAPI générées par IA (LLMs produisant des définitions d'API) ?

Particulièrement adapté. Les specs OpenAPI générées par LLM (à partir de prompts comme 'conçois une API pour X') tombent systématiquement dans les mêmes pièges : descriptions de réponse manquantes, paramètres de chemin déclarés mais absents de l'URL ou inversement, méthodes minuscules mélangées à majuscules, 401 manquant sur ops sécurisées, request bodies avec exemples mais sans schéma et réponses d'erreur oubliées. Collez la sortie LLM ici comme première vérification avant de la passer à un générateur de code ou outil de docs. La combinaison validation structurelle + tableau d'endpoints + warnings attrape environ 80 % des hallucinations LLM dans nos tests internes sur Claude, GPT-4 et Gemini.

L'outil supporte-t-il Swagger 2.0 ou seulement OpenAPI 3.x ?

Les specs Swagger 2.0 (`swagger: "2.0"` à la racine) sont détectées et marquées avec une recommandation de mise à niveau — l'outil n'exécute pas de règles de lint dessus. Swagger 2.0 a atteint le freeze des fonctionnalités en 2014 et l'écosystème (Spectral, Redocly, Stoplight, Postman, AWS API Gateway, Apigee, Kong) favorise OpenAPI 3.x. Convertissez avec `swagger2openapi spec.json` (paquet npm) qui gère 90%+ de la migration automatiquement : les types `body` passent dans requestBody, definitions vont dans components.schemas et `host`/`basePath`/`schemes` se replient dans le tableau servers. Après conversion, collez ici pour linter le résultat avant de merger.