Validateur OpenAPI : Vérifier votre Spec API

Qu'est-ce que le Validateur OpenAPI ?

Le Validateur OpenAPI est un outil basé sur le navigateur qui analyse et valide les fichiers de spécification OpenAPI 3.x et Swagger 2.0. Collez une spec en JSON ou YAML, cliquez sur Validate, et en quelques secondes vous verrez si la spec est structurellement valide, un décompte des chemins et opérations, et une liste d'avertissements pour les champs manquants importants pour les générateurs de SDK et les outils de documentation développeur.

L'outil s'exécute entièrement dans votre navigateur en utilisant la bibliothèque @readme/openapi-parser chargée à la demande. Aucun contenu de spec n'est envoyé à un serveur. Il est gratuit sans compte requis.

Utilisez-le avant de commiter une spec dans le contrôle de version, avant de publier de la documentation API, ou lors du débogage d'une spec qu'un outil en aval comme Swagger UI, Stoplight ou un générateur de SDK rejette.

Fonctionnalités principales

• Support OpenAPI 3.x et Swagger 2.0 : Le validateur accepte les deux formats. La bibliothèque sous-jacente @readme/openapi-parser gère les deux versions de spécification, y compris OpenAPI 3.1.
• Entrée JSON et YAML : L'outil essaie JSON.parse en premier, puis se rabat sur js-yaml pour l'entrée YAML. Vous n'avez pas besoin de déclarer quel format vous utilisez.
• Validation structurelle avec messages d'erreur précis : Lorsque la validation échoue, les messages d'erreur du parser sont divisés par sauts de ligne et affichés individuellement, chacun avec une référence de chemin le cas échéant.
• Avertissements de linting : Même lorsqu'une spec est structurellement valide, l'outil vérifie trois problèmes de qualité courants : info.description manquant, opérations sans description ni summary, et opérations sans operationId (requis pour la génération de SDK). Chaque avertissement affiche un décompte pour que vous connaissiez l'étendue du problème.
• Compteurs d'endpoints et d'opérations : Après une validation réussie, des tuiles de résumé affichent le titre de l'API, la chaîne de version, le nombre total de chemins et le nombre total d'opérations (à travers toutes les méthodes HTTP : get, post, put, patch, delete, head, options, trace).
• Bouton Charger l'exemple : Insère une spec OpenAPI 3.0 minimale mais complète avec un seul endpoint GET /users pour que vous puissiez voir à quoi ressemble une sortie valide avant de coller votre propre spec.
• Historique de validation : Les specs précédentes sont enregistrées dans la base de données IndexedDB du navigateur (fonctionnalité supporter) pour que vous puissiez les revisiter ou les restaurer sans les recoller.
• Traitement 100% côté client : Le parser et le validateur s'exécutent dans le navigateur. Le contenu de la spec ne quitte jamais votre machine.

Comment utiliser le Validateur OpenAPI

Étape 1 : Coller votre Spec

Cliquez dans la grande zone de texte intitulée « OpenAPI Specification (JSON or YAML) » et collez le contenu de votre spec. Le champ accepte du YAML ou JSON brut. Pour le YAML, incluez la déclaration de version en haut (openapi: "3.0.0" ou swagger: "2.0"). La zone de texte est en police monospace et affiche environ 15-20 lignes visibles.

Si vous souhaitez voir l'outil en action avant d'utiliser votre propre spec, cliquez sur le bouton « Load Example » dans le coin supérieur droit de la zone de texte. Il charge une spec OpenAPI 3.0 minimale avec un endpoint GET /users qui retourne un tableau d'objets utilisateur.

Étape 2 : Cliquer sur Validate Spec

Cliquez sur le bouton « Validate Spec » sous la zone de texte. Le bouton affiche « Validating... » pendant que le parser s'exécute (les bibliothèques @readme/openapi-parser et js-yaml sont chargées dynamiquement lors de la première utilisation, donc la première validation peut prendre un peu plus de temps que les suivantes).

La validation s'exécute sur la spec complète en mémoire. Pour l'entrée YAML, l'outil la convertit d'abord en un objet JavaScript avec js-yaml, puis passe l'objet au parser OpenAPI.

Étape 3 : Examiner le résultat de validation

Le panneau de résultat apparaît sous le bouton avec l'un des deux titres :

• « ✓ Valid OpenAPI Specification » en vert — la spec a passé la validation structurelle.
• « ✗ Validation Failed » en rouge — la spec a des erreurs structurelles qui doivent être corrigées.

L'en-tête du panneau affiche aussi des compteurs de badges : badges rouges pour les erreurs, badges jaunes pour les avertissements. Vous pouvez avoir une spec valide avec des avertissements — les avertissements indiquent des améliorations de qualité, pas des défaillances structurelles.

Étape 4 : Lire les tuiles de résumé (Specs valides)

Pour les specs qui passent la validation, quatre tuiles de résumé apparaissent au-dessus de la liste d'erreurs/avertissements :

• Title — la valeur de info.title
• Version — la valeur de info.version
• Paths — nombre total d'entrées de chemins (ex., /users, /users/{id})
• Operations — nombre total de combinaisons méthode HTTP+chemin (ex., un chemin avec GET et POST compte pour 2)

Ces chiffres sont utiles pour confirmer que vous validez le bon fichier, surtout lors de la gestion de plusieurs versions de specs.

Étape 5 : Traiter les avertissements

Trois types d'avertissements sont signalés même sur les specs valides :

1. info.description manquant — la spec manque d'une description générale de l'API. Cela apparaît dans Swagger UI et les portails développeurs et aide les utilisateurs à comprendre ce que fait l'API.
2. Opérations sans description ou summary — rapporté comme un compteur (ex., « 3 operation(s) missing description or summary »). description et summary sont tous deux vérifiés ; si l'un est présent, aucun avertissement n'est généré pour cette opération.
3. Opérations sans operationId — les générateurs de SDK (OpenAPI Generator, Kiota, etc.) utilisent operationId pour nommer les méthodes générées. Les valeurs manquantes font que les générateurs se rabattent sur des noms basés sur les chemins, qui sont souvent verbeux et incohérents.

Exemples pratiques

Exemple 1 : Trouver un champ requis manquant

Supposons que vous collez une spec Swagger 2.0 qui référence un $ref pointant vers une définition de schéma qui n'existe pas. Le validateur retournera :

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

Chaque ligne du message d'erreur du parser est affichée comme une entrée d'erreur séparée. Corrigez le chemin du $ref ou ajoutez la définition manquante, puis revalidez.

Exemple 2 : Spec valide avec avertissements de qualité

Une spec avec tous les éléments structurels requis mais sans valeurs operationId sur ses endpoints passe la validation mais affiche :

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

La spec peut être utilisée dans des outils comme Swagger UI immédiatement. Traitez les avertissements avant de la passer par un générateur de SDK.

Exemple 3 : Vérifier une grande spec d'un coup d'œil

Après avoir collé une spec d'API interne de 500 chemins, les tuiles de résumé affichent « Paths: 147 » et « Operations: 312 ». Si vous attendiez 150 chemins, vous savez qu'il faut investiguer pourquoi trois chemins manquent avant de commiter la spec.

Conseils et bonnes pratiques

Validez après chaque changement structurel. Ajouter un nouveau chemin, changer un $ref ou modifier un schéma peut introduire des erreurs qui n'apparaissent que lors du parsing de la spec complète. La validation prend moins de deux secondes, donc exécutez-la fréquemment.

Traitez les avertissements operationId comme des bloqueurs pour les workflows SDK. Si vous générez des SDKs clients depuis votre spec, toutes les opérations doivent avoir des valeurs operationId uniques. Les laisser non définies signifie que les noms de méthodes générés seront dérivés des chemins (ex., getUsersUserIdOrders au lieu de listOrders), ce qui est difficile à utiliser.

Utilisez l'exemple chargé comme modèle de départ. L'exemple intégré est une spec OpenAPI 3.0 complète, valide et minimale. Copiez-la depuis la zone de texte après le chargement et utilisez-la comme squelette pour une nouvelle spec plutôt que de commencer depuis un fichier vide.

Séparez la validité structurelle de l'exactitude sémantique. Le validateur confirme que votre spec suit le schéma OpenAPI. Il ne confirme pas que votre spec décrit fidèlement votre API réelle. Exécutez des tests d'intégration ou des tests de contrat pour vérifier l'exactitude sémantique.

Corrigez les erreurs du haut vers le bas. Une seule définition de schéma manquante peut causer des erreurs $ref en cascade dans toute la spec. Traitez l'erreur racine d'abord et revalidez avant de traiter les erreurs secondaires.

Problèmes courants et dépannage

« Parse error: ... » — l'entrée n'est ni du JSON valide ni du YAML valide. Causes courantes : une virgule finale en JSON ({"key": "value",}), une indentation YAML incohérente, ou un caractère de tabulation utilisé pour l'indentation YAML (YAML requiert des espaces). Corrigez la syntaxe et revalidez.

La validation échoue sur une spec que Swagger UI accepte. Swagger UI est tolérant et rendra les specs avec certaines violations structurelles. Le @readme/openapi-parser applique une validation stricte selon le JSON Schema officiel pour OpenAPI. Les erreurs montrées ici reflètent de véritables violations de spécification même si Swagger UI les ignore silencieusement.

Les avertissements apparaissent même après avoir ajouté des descriptions. L'outil vérifie à la fois description et summary sur les opérations, mais vérifie info.description séparément. Confirmez que vous avez ajouté description à l'intérieur de info, pas seulement sur les chemins individuels.

L'outil semble lent lors de la première utilisation. Les bibliothèques @readme/openapi-parser et js-yaml sont chargées dynamiquement lors du premier clic de validation. Les validations suivantes dans la même session de navigateur seront plus rapides car les modules sont déjà en mémoire.

Les longs messages d'erreur sont coupés. Les messages d'erreur du parser sont affichés en intégralité. Si un message est long, le texte s'ajuste dans sa ligne. Faites défiler la page pour lire le message complet s'il s'étend en dessous de la zone visible.

Confidentialité et sécurité

Le Validateur OpenAPI traite votre spec entièrement dans le navigateur. La bibliothèque @readme/openapi-parser s'exécute localement — aucun contenu de spec n'est envoyé à un service externe ou serveur. Cela signifie que vous pouvez valider en toute sécurité des specs d'API internes, des chemins d'endpoints privés et des définitions de schémas propriétaires sans risque d'exposition. L'outil fonctionne entièrement hors ligne une fois que la page et la bibliothèque du parser ont été chargées.

Questions fréquemment posées

Le Validateur OpenAPI est-il gratuit ? Oui. Il n'y a pas de coût, pas de compte ni de limite d'utilisation. Toutes les fonctionnalités de validation sont disponibles sans connexion.

Quelles versions d'OpenAPI sont supportées ? L'outil accepte Swagger 2.0, OpenAPI 3.0.x et OpenAPI 3.1.x. Le @readme/openapi-parser sous-jacent gère les trois versions. Le placeholder de la zone de texte indique « OpenAPI 2.0 / 3.0 / 3.1 » pour le refléter.

Puis-je coller du YAML ou faut-il du JSON ? Les deux formats fonctionnent. L'outil essaie JSON.parse d'abord, et si cela échoue, il utilise js-yaml pour parser le YAML. Vous n'avez pas besoin de convertir votre spec avant de la coller.

L'outil valide-t-il mes endpoints d'API réels ? Non. Le validateur vérifie que votre fichier de spec est structurellement correct selon le schéma OpenAPI. Il n'effectue aucune requête HTTP aux serveurs ou chemins listés dans votre spec.

Pourquoi ma spec échoue-t-elle ici mais fonctionne dans Swagger UI ? Swagger UI rend les specs avec une certaine tolérance aux erreurs. Ce validateur applique une validation stricte de schéma, qui détectera des problèmes que Swagger UI ignore silencieusement. Les deux comportements sont par conception — cet outil détecte les problèmes de qualité de la spec tôt, avant qu'ils ne causent des problèmes dans des consommateurs plus stricts comme les générateurs de SDK.

Que signifie « operationId required for SDK generation » ? Les générateurs de SDK comme OpenAPI Generator et Kiota nomment les méthodes générées d'après les valeurs operationId. Sans elles, les générateurs se rabattent sur la construction de noms à partir de la méthode HTTP et du chemin (ex., getApiV1UsersUserIdOrdersOrderId). Ajouter des valeurs operationId concises et uniques à chaque opération produit un code client généré beaucoup plus propre.

Y a-t-il des faux positifs dans les avertissements ? Les trois vérifications d'avertissement sont conservatrices. La vérification info.description ne se déclenche que lorsque le champ est absent ou vide. La vérification de description d'opération ne compte que les opérations auxquelles il manque à la fois description et summary — avoir l'un ou l'autre supprime l'avertissement pour cette opération. La vérification operationId est stricte : chaque opération qui en manque est comptée.

Puis-je valider un fichier de spec plutôt que de le coller ? L'outil accepte uniquement du texte collé — il n'y a pas de bouton d'upload de fichier. Ouvrez votre fichier de spec dans un éditeur de texte, sélectionnez tout et collez le contenu dans la zone de texte.

Le panneau d'historique sauvegarde-t-il le contenu de ma spec ? Oui. Lorsque vous validez une spec avec succès, l'outil enregistre une entrée dans l'historique IndexedDB de votre navigateur (fonctionnalité supporter) contenant la spec d'entrée et le résumé de validation. L'historique est local à votre navigateur et n'est jamais synchronisé avec un serveur.

Que se passe-t-il si je colle une spec vide ? Le bouton Validate est désactivé lorsque la zone de texte est vide (disabled={!input.trim()}). Vous devez entrer au moins un caractère non-espace avant que le bouton ne devienne cliquable.

Outils associés

• Bientôt disponible: Générateur de Mock d'API — générez des données de réponse mock à partir de votre spec validée pour l'utiliser dans le développement frontend.
• Bientôt disponible: Suite de Conception d'API — concevez et itérez sur la structure de l'API avant d'exporter au format OpenAPI.
• Formateur JSON — formatez et validez la structure JSON de votre spec avant de la coller dans le validateur.

Essayez le Validateur OpenAPI maintenant : Validateur OpenAPI