YAML per la scrittura
Le descrizioni lunghe si leggono meglio come testo a blocco YAML, e i commenti permettono di annotare la specifica per chi la rivede.
Converti specifiche API tra JSON e YAML senza rompere i percorsi $ref o i codici di risposta.
Ogni riga dell'output, con la formattazione predefinita, accanto al percorso del valore che contiene. Fai clic su una riga per copiare il percorso.
Funziona interamente nel tuo browser: nulla viene caricato. Si applicano limiti di uso corretto (5 MB per input, numero di conversioni limitato) per prevenire spam e bot.
Due dettagli rompono le specifiche convertite a mano: un # che apre un commento YAML e i codici di stato che diventano interi. Entrambi vengono gestiti.
{
"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 Scegli A mano, senza virgolette per vedere il $ref diventare null e l'host con wildcard non superare il parsing.
Dopo la conversione, esegui un linter per controllare la specifica stessa, non solo la sintassi. Qui ogni $ref locale viene verificato mentre modifichi.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Le descrizioni lunghe si leggono meglio come testo a blocco YAML, e i commenti permettono di annotare la specifica per chi la rivede.
Generatori di codice, gateway e SDK spesso caricano il JSON più velocemente, e molti servono la specifica su /openapi.json.
Entrambi i formati descrivono la stessa API. Converti liberamente in entrambe le direzioni; nulla della specifica va perso.
Convertitori, validatori e guide passo passo per ogni punto in cui JSON e YAML si incontrano.
Incolla o carica openapi.json e copia lo YAML dal riquadro di destra, oppure scaricalo come openapi.yaml. Struttura, puntatori $ref, esempi e descrizioni restano identici.
Sì. Il convertitore lavora sulla struttura del documento, quindi le specifiche Swagger 2.0, OpenAPI 3.0 e OpenAPI 3.1 si convertono allo stesso modo, in entrambe le direzioni.
In YAML, # apre un commento quando segue uno spazio. Senza virgolette, tutto ciò che segue $ref: verrebbe trattato come commento e il riferimento resterebbe vuoto. Il convertitore lo mette tra virgolette automaticamente.
OpenAPI richiede che i codici di risposta siano chiavi stringa. Un 200 senza virgolette è un intero in YAML; la maggior parte degli strumenti lo accetta, ma i validatori rigorosi no. Le virgolette mantengono la specifica valida ovunque.
Imposta la direzione su YAML → JSON con il selettore sopra l'editor, oppure usa il convertitore da YAML a JSON. Le ancore nello YAML vengono espanse, perché JSON non ha riferimenti di quel tipo.