OpenAPI e Swagger de JSON para YAML

Converta especificações de API entre JSON e YAML sem quebrar caminhos $ref nem códigos de resposta.

Opções de saída

JSONentrada

Vazio

YAMLsaída

A saída YAML aparece aqui

Funciona inteiramente no seu navegador: nada é enviado. Limites de uso justo se aplicam (5 MB por entrada, conversões com limite de frequência) para evitar spam e bots.

Carregar de URL

O arquivo é buscado diretamente pelo seu navegador, portanto o servidor precisa permitir requisições de outras origens.

Atalhos de teclado

Ctrl / ⌘ + Enter Converter agora
Ctrl / ⌘ + S Baixar a saída
Alt + Shift + C Copiar a saída
Alt + Shift + F Corrigir e formatar o JSON de entrada
Alt + Shift + S Inverter a direção
Alt + Shift + T Alternar entre as visualizações de código, árvore e mapa
Ctrl / ⌘ + Z Desfazer, inclusive Formatar, Corrigir e Limpar
Esc Sair da tela cheia
Tamanho do texto do editor

Ponteiros $ref e códigos de resposta continuam válidos

Dois detalhes quebram especificações convertidas à mão: um # que inicia um comentário YAML e códigos de status que viram inteiros. Os dois são tratados.

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

Escolha À mão, sem aspas para ver o $ref virar null e o host com curinga falhar na análise.

Rode o lint no resultado

Depois de converter, rode um linter para verificar a especificação em si, não só a sintaxe. Aqui, cada $ref local é verificado enquanto você edita.

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

JSON ou YAML para especificações de API?

YAML para escrever

Descrições longas ficam mais legíveis como texto de bloco YAML, e comentários permitem anotar a especificação para os revisores.

JSON para ferramentas

Geradores de código, gateways e SDKs costumam carregar JSON mais rápido, e muitos servem a especificação em /openapi.json.

O mesmo documento

Os dois formatos descrevem a mesma API. Converta à vontade em qualquer direção; nada da especificação se perde.

Mais ferramentas

Conversores, validadores e guias passo a passo para cada lugar onde JSON e YAML se encontram.

Perguntas frequentes

Como converto um arquivo OpenAPI JSON para YAML?

Cole ou faça upload do openapi.json e copie o YAML do painel da direita, ou baixe-o como openapi.yaml. A estrutura, os ponteiros $ref, os exemplos e as descrições são mantidos exatamente.

Funciona com Swagger 2.0 além de OpenAPI 3?

Sim. O conversor trabalha na estrutura do documento, então especificações Swagger 2.0, OpenAPI 3.0 e OpenAPI 3.1 são convertidas da mesma forma, nas duas direções.

Por que $ref: '#/components/...' fica entre aspas?

No YAML, # inicia um comentário quando vem depois de um espaço. Sem aspas, tudo o que vem depois de $ref: seria tratado como comentário e a referência ficaria vazia. O conversor coloca as aspas automaticamente.

Por que os códigos de resposta são escritos como '200'?

O OpenAPI exige que os códigos de resposta sejam chaves string. Um 200 sem aspas é um inteiro no YAML; a maioria das ferramentas aceita, mas validadores estritos não. As aspas mantêm a especificação válida em qualquer lugar.

Como converto YAML do OpenAPI de volta para JSON?

Mude a direção para YAML → JSON com o seletor acima do editor ou use o conversor de YAML para JSON. As âncoras do YAML são expandidas, já que o JSON não tem referências desse tipo.