OpenAPI et Swagger : JSON en YAML

Convertissez des spécifications d'API entre JSON et YAML sans casser les chemins $ref ni les codes de réponse.

Options de sortie

JSONentrée

Vide

YAMLsortie

La sortie YAML s'affiche ici

Fonctionne entièrement dans votre navigateur: rien n'est envoyé. Des limites d'usage raisonnable s'appliquent (5 MB par entrée, nombre de conversions limité) pour éviter le spam et les robots.

Charger depuis une URL

Le fichier est récupéré directement par votre navigateur : le serveur doit donc autoriser les requêtes cross-origin.

Raccourcis clavier

Ctrl / ⌘ + Enter Convertir maintenant
Ctrl / ⌘ + S Télécharger la sortie
Alt + Shift + C Copier la sortie
Alt + Shift + F Réparer et formater le JSON d'entrée
Alt + Shift + S Inverser le sens
Alt + Shift + T Basculer entre les vues code, arbre et correspondance
Ctrl / ⌘ + Z Annuler, y compris Formater, Réparer et Effacer
Esc Quitter le plein écran
Taille du texte de l'éditeur

Les pointeurs $ref et les codes de réponse restent valides

Deux détails cassent les spécifications converties à la main : un # qui ouvre un commentaire YAML, et des codes de statut qui deviennent des entiers. Les deux sont gérés.

openapi.json
{
  "paths": {
    "/pets/{id}": {
      "get": {
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error"
          }
        }
      }
    }
  }
}
openapi.yaml
paths:
  /pets/{id}:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        4XX:
          description: Client error

Choisissez À la main, sans guillemets pour voir le $ref devenir null et l'hôte générique échouer à l'analyse.

Passer le résultat au linter

Après la conversion, lancez un linter pour vérifier la spécification elle-même, pas seulement sa syntaxe. Ici, chaque $ref local est vérifié pendant l'édition.

bash
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml

JSON ou YAML pour les spécifications d'API ?

YAML pour la rédaction

Les longues descriptions se lisent mieux en texte de bloc YAML, et les commentaires permettent d'annoter la spécification pour les relecteurs.

JSON pour l'outillage

Les générateurs de code, passerelles et SDK chargent souvent le JSON plus vite, et beaucoup servent la spécification à /openapi.json.

Le même document

Les deux formats décrivent la même API. Convertissez librement dans un sens ou dans l'autre ; rien de la spécification n'est perdu.

Autres outils

Convertisseurs, validateurs et guides pas à pas pour tous les endroits où JSON et YAML se croisent.

Questions fréquentes

Comment convertir un fichier OpenAPI JSON en YAML ?

Collez ou importez openapi.json et copiez le YAML depuis le panneau de droite, ou téléchargez-le sous le nom openapi.yaml. La structure, les pointeurs $ref, les exemples et les descriptions sont conservés à l'identique.

Est-ce que ça fonctionne pour Swagger 2.0 comme pour OpenAPI 3 ?

Oui. Le convertisseur travaille sur la structure du document : les spécifications Swagger 2.0, OpenAPI 3.0 et OpenAPI 3.1 se convertissent de la même façon, dans les deux sens.

Pourquoi $ref: '#/components/...' est-il entre guillemets ?

En YAML, # ouvre un commentaire lorsqu'il suit un espace. Sans guillemets, tout ce qui suit $ref: serait traité comme un commentaire et la référence serait vide. Le convertisseur ajoute les guillemets automatiquement.

Pourquoi les codes de réponse sont-ils écrits '200' ?

OpenAPI exige que les codes de réponse soient des clés de type chaîne. Un 200 sans guillemets est un entier en YAML ; la plupart des outils l'acceptent, mais pas les validateurs stricts. Les guillemets gardent la spécification valide partout.

Comment reconvertir du YAML OpenAPI en JSON ?

Passez le sens à YAML → JSON avec le sélecteur au-dessus de l'éditeur, ou utilisez le convertisseur YAML en JSON. Les ancres du YAML sont développées, car JSON n'a pas de références de ce type.