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 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, 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.

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.

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.