Cette visionneuse et ce validateur OpenAPI lisent un document OpenAPI 3.0, 3.1 ou Swagger 2.0 en YAML ou JSON et l’affichent sous forme de documentation d’API navigable : chaque endpoint classé par tag, avec ses paramètres, son corps de requête, ses réponses et ses schémas, ainsi qu’une commande cURL prête à l’emploi. Collez la spécification ou ouvrez le fichier ; rien n’est envoyé, donc les API internes et non publiées restent privées.
Le validateur effectue 23 vérifications de structure issues des spécifications, toutes listées sur la page : présence de info et de paths, réponses avec description et codes d’état valides, chaque {parameter} d’un chemin déclaré comme paramètre de chemin obligatoire, operationId uniques, $ref résolus, et exigences de sécurité qui désignent un schéma défini. Ce sont les erreurs qui cassent les générateurs de code et les outils de documentation. Il ne s’agit pas d’une validation complète selon le JSON Schema officiel de la spécification : une spec qui passe ici peut encore contenir, par exemple, un mot-clé de schéma mal orthographié. Les $ref externes vers d’autres fichiers sont listés mais pas téléchargés.
Mode d’emploi
- Collez votre openapi.yaml, openapi.json ou swagger.json, ou ouvrez le fichier. Une API d’exemple est chargée pour commencer.
- Lisez la ligne d’état et la liste Validation. Chaque problème indique la règle et son emplacement (par exemple paths./pets/{id}.get).
- Parcourez la documentation : les opérations sont classées par tag ; cliquez sur l’une d’elles pour voir ses paramètres, son corps de requête, ses réponses et ses schémas.
- Filtrez par chemin, résumé ou operationId pour trouver un endpoint dans une grosse spécification.
- Copiez l’exemple cURL d’une opération et remplacez l’espace réservé <TOKEN> ou <API_KEY> par vos identifiants.
Questions fréquentes
Comment afficher un fichier Swagger ou OpenAPI ?
Collez le YAML ou le JSON dans la zone ou ouvrez le fichier. La visionneuse détecte la version (swagger: "2.0" ou openapi: 3.0.x / 3.1.x), liste les endpoints classés par tag et vous permet de déplier chacun pour voir ses paramètres, son corps de requête, ses réponses et ses schémas résolus. Elle fonctionne hors ligne une fois la page chargée.
Que vérifie le validateur OpenAPI ?
Des règles de structure issues de la spécification : un champ de version pris en charge ; info avec title et version ; des chemins commençant par / ; des opérations avec des responses non vides qui ont une description et des codes d’état valides ; des paramètres de gabarit de chemin déclarés et obligatoires ; des paramètres avec name, un in valide et un schema ; aucun paramètre ni operationId en double ; des corps de requête avec content ; des $ref résolus ; et des exigences de sécurité qui désignent des schémas définis. La liste complète figure sur la page sous « Ce qui est vérifié ». Il ne valide pas chaque mot-clé de schéma selon le JSON Schema officiel.
Pourquoi un paramètre de chemin non déclaré est-il une erreur ?
La spécification exige que chaque {name} d’un gabarit de chemin ait un paramètre correspondant avec in: path et required: true, au niveau du chemin ou de l’opération. Certains validateurs qui se contentent de vérifier le document selon le JSON Schema acceptent qu’il manque, mais les générateurs de code produisent alors une fonction sans argument pour lui, et les outils de documentation affichent un endpoint qu’on ne peut pas appeler correctement.
Peut-il lire OpenAPI 3.1 et Swagger 2.0 ?
Oui. Les paramètres body et formData de Swagger 2.0 sont affichés comme corps de requête, avec produces et consumes comme types de média : les trois versions se lisent donc de la même façon. Les différences d’OpenAPI 3.1 sont respectées : paths est facultatif quand components ou webhooks sont présents, responses est facultatif (un avertissement ici), et type: [string, "null"] est affiché comme nullable.
Charge-t-il les fichiers $ref externes ?
Non. Un $ref vers un autre fichier ou une URL (par exemple ./schemas/user.yaml) est listé comme avertissement et affiché comme non résolu, car la page ne peut pas lire des fichiers que vous n’avez pas ouverts et ne télécharge pas d’URL d’elle-même. Regroupez d’abord une spécification en plusieurs fichiers en un seul document, par exemple avec redocly bundle ou swagger-cli bundle.
Ma spécification d’API est-elle envoyée ?
Non. L’analyse, la validation et l’affichage se font dans votre navigateur. La spécification n’est jamais envoyée nulle part.
OpenAPI 3.x et Swagger 2.0 : ce qui a changé
• Champ de version : swagger: "2.0" est devenu openapi: 3.0.x, puis 3.1.x.
• Serveurs : la 2.0 a host, basePath et schemes ; la 3.x a une liste servers avec des variables.
• Corps de requête : la 2.0 utilise un paramètre avec in: body (ou formData) ; la 3.x a requestBody avec un content par type de média.
• Éléments réutilisables : en 2.0, definitions, parameters et responses au premier niveau ; la 3.x les place sous components, avec securitySchemes, requestBodies et examples.
• La 3.1 aligne les schémas sur JSON Schema 2020-12 : type peut être une liste (["string", "null"] au lieu de nullable: true), examples est un tableau, et les webhooks font leur apparition.
Les erreurs qui cassent le plus souvent les outils d’API
• Des paramètres de chemin non déclarés, ou déclarés sans required: true.
• Un $ref avec une faute de frappe (#/components/schema/User au lieu de schemas), qui laisse une partie de la documentation vide.
• Des operationId en double, qui font échouer les générateurs de code ou écrasent des méthodes.
• Des réponses sans description (elle est obligatoire, même si ce n’est que "OK").
• Une exigence de sécurité qui désigne un schéma non défini : le client généré n’a alors aucun moyen de s’authentifier.
