Aller au contenu

Visionneuse et validateur OpenAPI et Swagger — YAML ou JSON

Collez une spécification OpenAPI 3.x ou Swagger 2.0 pour la parcourir comme une documentation classée par tag, y détecter les erreurs de structure et obtenir un exemple cURL par endpoint.

OpenAPI 3.0 · Bookstore API 1.2.0 · 4 opérations · 1 erreur, 0 avertissement

Validation

  • Erreur Le chemin utilise {itemId} mais aucun paramètre in: path nommé « itemId » n’est déclaré.
    à paths./orders/{orderId}/items/{itemId}.get
Ce qui est vérifié

La visionneuse vérifie ces règles de structure issues des spécifications OpenAPI 3.0 / 3.1 et Swagger 2.0. Il ne s’agit pas d’une validation JSON Schema complète du document : les mots-clés de schéma individuels (minimum, pattern, format…) ne sont pas vérifiés.

  • Le document est du YAML ou du JSON valide.
  • Il déclare openapi: 3.0.x ou 3.1.x, ou swagger: "2.0".
  • info existe avec un title et une version (chaînes).
  • paths existe (facultatif en 3.1 quand components ou webhooks sont présents).
  • Chaque chemin commence par /.
  • Les éléments de chemin ne contiennent que des méthodes HTTP, parameters, $ref, summary, description, servers (ou des extensions x-).
  • Chaque opération a des responses (une erreur en 2.0 et 3.0, un avertissement en 3.1).
  • responses n’est pas vide.
  • Les clés de réponse sont des codes d’état (200), default ou (3.x) des plages comme 2XX.
  • Chaque réponse a une description.
  • Les valeurs d’operationId sont uniques.
  • Chaque {name} d’un chemin a un paramètre in: path correspondant.
  • Chaque paramètre in: path apparaît dans le chemin.
  • Les paramètres de chemin ont required: true.
  • Chaque paramètre a name et in.
  • in vaut query, header, path ou cookie (2.0 : query, header, path, formData ou body).
  • Aucun paramètre n’est listé deux fois avec les mêmes name et in.
  • Les paramètres ont un schema ou un content (2.0 : les paramètres body ont un schema, les autres un type).
  • 2.0 : au plus un paramètre body, et pas en même temps que formData.
  • 3.x : requestBody a un content.
  • Chaque $ref local (#/…) pointe vers quelque chose qui existe.
  • Les références vers d’autres fichiers ou URL sont signalées (elles ne sont pas téléchargées).
  • Les exigences de sécurité désignent un schéma de sécurité défini.

Documentation: Bookstore API 1.2.0

A small example API. Edit it or paste your own spec.

URL de base : https://api.example-bookstore.com/v1

Books

Browse and manage the catalogue

GET/booksList books
POST/booksAdd a book
GET/books/{bookId}Get one book

Orders

Place and track orders

GET/orders/{orderId}/items/{itemId}Get an order line

Schémas

NewBook
Book
Author
OrderItem

Fonctionne entièrement dans votre navigateur. Votre spécification d’API n’est jamais envoyée, et les $ref externes ne sont pas téléchargés. Parcourir tous les outils gratuits.

Un problème, ou quelque chose à améliorer ? Nous lisons chaque message et corrigeons vite.

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

  1. Collez votre openapi.yaml, openapi.json ou swagger.json, ou ouvrez le fichier. Une API d’exemple est chargée pour commencer.
  2. 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).
  3. 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.
  4. Filtrez par chemin, résumé ou operationId pour trouver un endpoint dans une grosse spécification.
  5. 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.