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.
Converta especificações de API entre JSON e YAML sem quebrar caminhos $ref nem códigos de resposta.
Cada linha da saída, com a formatação padrão, ao lado do caminho do valor que ela contém. Clique em uma linha para copiar o caminho.
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.
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.
{
"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 Escolha À mão, sem aspas para ver o $ref virar null e o host com curinga falhar na análise.
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.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Descrições longas ficam mais legíveis como texto de bloco YAML, e comentários permitem anotar a especificação para os revisores.
Geradores de código, gateways e SDKs costumam carregar JSON mais rápido, e muitos servem a especificação em /openapi.json.
Os dois formatos descrevem a mesma API. Converta à vontade em qualquer direção; nada da especificação se perde.
Conversores, validadores e guias passo a passo para cada lugar onde JSON e YAML se encontram.
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.
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.
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.
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.
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.