OpenAPI e Swagger da JSON a YAML

Converti specifiche API tra JSON e YAML senza rompere i percorsi $ref o i codici di risposta.

Opzioni di output

JSONinput

Vuoto

YAMLoutput

L'output YAML appare qui

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.

Carica da URL

Il file viene recuperato direttamente dal tuo browser, quindi il server deve consentire le richieste cross-origin.

Scorciatoie da tastiera

Ctrl / ⌘ + Enter Converti ora
Ctrl / ⌘ + S Scarica l'output
Alt + Shift + C Copia l'output
Alt + Shift + F Ripara e formatta il JSON di input
Alt + Shift + S Inverti la direzione
Alt + Shift + T Passa tra le viste codice, albero e mappa
Ctrl / ⌘ + Z Annulla, anche dopo Formatta, Ripara e Cancella
Esc Esci da schermo intero
Dimensione del testo nell'editor

Puntatori $ref e codici di risposta restano validi

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.

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

Scegli A mano, senza virgolette per vedere il $ref diventare null e l'host con wildcard non superare il parsing.

Esegui il lint del risultato

Dopo la conversione, esegui un linter per controllare la specifica stessa, non solo la sintassi. Qui ogni $ref locale viene verificato mentre modifichi.

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

JSON o YAML per le specifiche API?

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.

JSON per gli strumenti

Generatori di codice, gateway e SDK spesso caricano il JSON più velocemente, e molti servono la specifica su /openapi.json.

Stesso documento

Entrambi i formati descrivono la stessa API. Converti liberamente in entrambe le direzioni; nulla della specifica va perso.

Altri strumenti

Convertitori, validatori e guide passo passo per ogni punto in cui JSON e YAML si incontrano.

Domande frequenti

Come converto un file OpenAPI JSON in YAML?

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.

Funziona con Swagger 2.0 oltre che con OpenAPI 3?

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.

Perché $ref: '#/components/...' è tra virgolette?

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.

Perché i codici di risposta sono scritti come '200'?

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.

Come riconverto lo YAML di OpenAPI in JSON?

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.