¿Cómo admite OpenAPI los formatos JSON y YAML?

¿Cómo admite OpenAPI los formatos JSON y YAML? #

En el mundo de las API web modernas, OpenAPI se ha consolidado como un potente estándar para definir y documentar API. Una de las muchas fortalezas de OpenAPI es su compatibilidad con los formatos JSON y YAML. Esta versatilidad permite a los desarrolladores elegir el formato que mejor se adapte a sus necesidades y preferencias. En este artículo analizaremos cómo admite OpenAPI los formatos JSON y YAML, y exploraremos los beneficios de cada uno.

Comprender OpenAPI #

Antes de hablar de cómo admite OpenAPI JSON y YAML, es importante tener una comprensión básica de qué es OpenAPI. OpenAPI, antes conocido como Swagger, es una especificación para definir cómo deben construirse y describirse las API RESTful. Con OpenAPI, los desarrolladores pueden crear documentación de API completa y legible por máquinas que facilita la integración y el uso de las API.

La especificación OpenAPI está mantenida por la OpenAPI Initiative, un consorcio de líderes de la industria que incluye a Google, Microsoft e IBM. La línea de versión principal de la especificación es OpenAPI 3.x, introducida en 2017 como una mejora significativa respecto de la anterior especificación Swagger 2.0, y que a finales de 2025 se encuentra en la versión 3.2.

JSON y YAML: descripción general de los formatos #

JSON (JavaScript Object Notation) #

JSON es un formato ligero de intercambio de datos, fácil de leer y escribir para las personas y fácil de analizar y generar para las máquinas. La sintaxis de JSON deriva de la notación de objetos de JavaScript, pero es independiente del lenguaje y es compatible con numerosos lenguajes de programación. JSON se utiliza ampliamente en las API web por su simplicidad y su amplia compatibilidad.

Ejemplo de JSON:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "description": "This is a sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/example": {
      "get": {
        "summary": "Example endpoint",
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    }
  }
}

YAML (YAML Ain’t Markup Language) #

YAML es un estándar de serialización de datos legible por personas que se utiliza a menudo para archivos de configuración y para el intercambio de datos entre lenguajes con distintas estructuras de datos. Una de las principales ventajas de YAML frente a JSON es que tiende a ser más legible, ya que utiliza sangría en lugar de llaves y corchetes.

Ejemplo de YAML:

openapi: 3.0.0
info:
  title: Sample API
  description: This is a sample API
  version: 1.0.0
paths:
  /example:
    get:
      summary: Example endpoint
      responses:
        '200':
          description: Successful response

Cómo admite OpenAPI JSON y YAML #

La propia especificación OpenAPI puede escribirse en formato JSON o YAML. La elección entre JSON y YAML suele ser una cuestión de preferencia y de contexto. Así es como OpenAPI admite ambos formatos:

Flexibilidad en la elección del formato #

La especificación oficial de OpenAPI permite escribir la definición completa de la API en JSON o en YAML. Esta flexibilidad significa que los desarrolladores pueden elegir el formato que les resulte más legible o más adecuado para su proyecto. Como ambos formatos son compatibles, la misma definición de la API puede convertirse de un formato a otro sin ninguna pérdida de información.

Herramientas y bibliotecas #

Existen numerosas herramientas y bibliotecas para trabajar con OpenAPI tanto en formato JSON como en YAML. Estas herramientas facilitan la creación, la validación y la conversión de especificaciones de API. Algunas de las herramientas más populares son:

  • Swagger Editor: un editor web para diseñar especificaciones OpenAPI en formatos JSON y YAML. El editor ofrece validación en tiempo real y una vista previa de la documentación de la API.
  • Swagger Codegen: una herramienta para generar bibliotecas de cliente, esqueletos de servidor, documentación de la API y archivos de configuración a partir de una especificación OpenAPI.
  • OpenAPI Generator: una bifurcación (fork) de Swagger Codegen impulsada por la comunidad, que admite más lenguajes y ofrece funciones adicionales.

Conversión entre formatos #

La conversión entre JSON y YAML es sencilla y puede hacerse con diversas herramientas y bibliotecas. Algunos métodos populares son:

  • Usar Swagger Editor, que permite alternar sin complicaciones entre las vistas JSON y YAML.
  • Emplear herramientas de línea de comandos como swagger-cli u openapi-generator para convertir archivos.
  • Escribir scripts personalizados en lenguajes de programación como Python, con bibliotecas como PyYAML para analizar YAML y json para analizar JSON.

Ejemplos de conversión #

A continuación se muestran un par de ejemplos que demuestran lo fácil que es convertir una definición OpenAPI entre JSON y YAML.

Conversión de JSON a YAML:

Con el paquete npm yaml en un script de Node.js:

const fs = require('fs');
const yaml = require('js-yaml');

const jsonContent = fs.readFileSync('openapi.json', 'utf8');
const jsonParsed = JSON.parse(jsonContent);
const yamlContent = yaml.dump(jsonParsed);

fs.writeFileSync('openapi.yaml', yamlContent);

Conversión de YAML a JSON:

Con un script de Python y PyYAML:

import yaml
import json

with open('openapi.yaml', 'r') as yaml_file:
    yaml_content = yaml.safe_load(yaml_file)
    json_content = json.dumps(yaml_content, indent=2)

with open('openapi.json', 'w') as json_file:
    json_file.write(json_content)

Beneficios de JSON y YAML en OpenAPI #

Cada formato ofrece ventajas distintas, y la elección entre JSON y YAML depende en gran medida del caso de uso concreto y de las preferencias de cada desarrollador.

Beneficios de JSON #

  1. Estandarización: JSON es un formato estandarizado, con un uso muy extendido y compatible con distintos lenguajes de programación.
  2. Rendimiento: el análisis y la generación de JSON suelen ser más rápidos que los de YAML debido a su estructura más simple.
  3. Idoneidad para las API: JSON suele ser la opción predeterminada para las API web, lo que lo convierte en una opción natural para las especificaciones OpenAPI.
  4. Menos ambigüedad: la sintaxis explícita de JSON reduce las posibilidades de ambigüedad o malas interpretaciones.

Beneficios de YAML #

  1. Legibilidad: la estructura de YAML, basada en sangría, suele ser más legible y concisa que las llaves y los corchetes de JSON.
  2. Facilidad de escritura: la sintaxis de YAML es menos extensa y más amigable para las personas, lo que puede ser una ventaja al escribir especificaciones de API manualmente.
  3. Archivos de configuración: YAML se utiliza a menudo para archivos de configuración en diversas aplicaciones, por lo que es un formato familiar para muchos desarrolladores.

Conclusión #

La compatibilidad de OpenAPI con los formatos JSON y YAML ofrece a los desarrolladores la flexibilidad de elegir el formato que mejor se ajuste a sus necesidades. Tanto si prefieres la simplicidad y el rendimiento de JSON como la legibilidad y la concisión de YAML, OpenAPI te ofrece ambas opciones. La disponibilidad de diversas herramientas y bibliotecas facilita aún más el trabajo con estos formatos, y asegura que OpenAPI siga siendo una solución potente y versátil para definir y documentar API RESTful.

Para obtener más información sobre OpenAPI y sus especificaciones, puedes visitar la OpenAPI Initiative y explorar su amplia documentación y sus recursos.

Última actualización: 12 de agosto de 2026.

Este sitio web no está afiliado a la OpenAPI Initiative.