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.
Convertissez des spécifications d'API entre JSON et YAML sans casser les chemins $ref ni les codes de réponse.
Chaque ligne de la sortie, en mise en forme par défaut, à côté du chemin de la valeur qu'elle contient. Cliquez sur une ligne pour copier le chemin.
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.
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.
{
"paths": {
"/pets/{id}": {
"get": {
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"4XX": {
"description": "Client error"
}
}
}
}
}
} 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.
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.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Les longues descriptions se lisent mieux en texte de bloc YAML, et les commentaires permettent d'annoter la spécification pour les relecteurs.
Les générateurs de code, passerelles et SDK chargent souvent le JSON plus vite, et beaucoup servent la spécification à /openapi.json.
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.
Convertisseurs, validateurs et guides pas à pas pour tous les endroits où JSON et YAML se croisent.
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.
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.
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.
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.
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.