YAML para redactar
Las descripciones largas se leen mejor como texto de bloque YAML, y los comentarios te permiten anotar la especificación para los revisores.
Convierte especificaciones de API entre JSON y YAML sin romper las rutas $ref ni los códigos de respuesta.
Cada línea de la salida, con el formato predeterminado, junto a la ruta del valor que contiene. Haz clic en una fila para copiar la ruta.
Se ejecuta íntegramente en tu navegador: no se sube nada. Se aplican límites de uso razonable (5 MB por entrada, conversiones con límite de frecuencia) para evitar el spam y los bots.
Dos detalles rompen las especificaciones convertidas a mano: un # que inicia un comentario YAML y los códigos de estado que se convierten en enteros. Ambos están resueltos.
{
"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 Elige A mano, sin comillas para ver cómo el $ref se convierte en null y el host comodín no se puede analizar.
Después de convertir, ejecuta un linter para comprobar la propia especificación, no solo su sintaxis. Aquí se comprueba cada $ref local mientras editas.
# Lint the converted spec (OpenAPI 3.x and Swagger 2.0)
npx @redocly/cli lint openapi.yaml Las descripciones largas se leen mejor como texto de bloque YAML, y los comentarios te permiten anotar la especificación para los revisores.
Los generadores de código, las pasarelas y los SDK suelen cargar JSON más rápido, y muchos sirven la especificación en /openapi.json.
Ambos formatos describen la misma API. Convierte libremente en cualquier sentido; no se pierde nada de la especificación.
Conversores, validadores y guías paso a paso para cada lugar donde se encuentran JSON y YAML.
Pega o sube openapi.json y copia el YAML del panel derecho, o descárgalo como openapi.yaml. La estructura, los punteros $ref, los ejemplos y las descripciones se mantienen exactamente igual.
Sí. El conversor trabaja sobre la estructura del documento, así que las especificaciones Swagger 2.0, OpenAPI 3.0 y OpenAPI 3.1 se convierten igual, en ambos sentidos.
En YAML, # inicia un comentario cuando sigue a un espacio. Sin comillas, todo lo que va después de $ref: se trataría como un comentario y la referencia quedaría vacía. El conversor lo entrecomilla automáticamente.
OpenAPI exige que los códigos de respuesta sean claves de tipo cadena. Un 200 sin comillas es un entero en YAML; la mayoría de las herramientas lo aceptan, pero los validadores estrictos no. Las comillas mantienen la especificación válida en todas partes.
Cambia la dirección a YAML → JSON con el selector que hay sobre el editor, o usa el conversor de YAML a JSON. Las anclas del YAML se expanden, ya que JSON no tiene referencias de ese tipo.