OpenAPI y Swagger: JSON a YAML

Convierte especificaciones de API entre JSON y YAML sin romper las rutas $ref ni los códigos de respuesta.

Opciones de salida

JSONentrada

Vacío

YAMLsalida

La salida YAML aparece aquí

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.

Cargar desde URL

Tu navegador obtiene el archivo directamente, por lo que el servidor debe permitir solicitudes de origen cruzado.

Atajos de teclado

Ctrl / ⌘ + Enter Convertir ahora
Ctrl / ⌘ + S Descargar la salida
Alt + Shift + C Copiar la salida
Alt + Shift + F Reparar y formatear el JSON de entrada
Alt + Shift + S Invertir la dirección
Alt + Shift + T Alternar entre las vistas de código, árbol y mapa
Ctrl / ⌘ + Z Deshacer, incluidos Formatear, Reparar y Borrar
Esc Salir de pantalla completa
Tamaño del texto del editor

Los punteros $ref y los códigos de respuesta siguen siendo válidos

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.

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

Elige A mano, sin comillas para ver cómo el $ref se convierte en null y el host comodín no se puede analizar.

Pasa un linter al resultado

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.

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

¿JSON o YAML para especificaciones de API?

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.

JSON para las herramientas

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.

El mismo documento

Ambos formatos describen la misma API. Convierte libremente en cualquier sentido; no se pierde nada de la especificación.

Más herramientas

Conversores, validadores y guías paso a paso para cada lugar donde se encuentran JSON y YAML.

Preguntas frecuentes

¿Cómo convierto un archivo OpenAPI JSON a 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.

¿Funciona con Swagger 2.0 además de con OpenAPI 3?

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.

¿Por qué $ref: '#/components/...' va entre comillas?

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.

¿Por qué los códigos de respuesta se escriben como '200'?

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.

¿Cómo convierto YAML de OpenAPI de nuevo a JSON?

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.