OpenAPI es ese estándar clave para describir APIs de forma que tanto humanos como máquinas puedan entenderlas. A partir de un archivo OpenAPI, los desarrolladores pueden validar su API, correr tests automáticos, generar documentación al instante y los consumidores pueden usarlo para integrarse fácil y rápido.
Aunque OpenAPI no es algo nuevo, los últimos meses han traído movimiento: nuevas versiones, nuevas especificaciones y un rumbo claro para el futuro. Te cuento qué hay de nuevo y por qué deberías estar pendiente.
Dos Nuevas Especificaciones: Overlay y Arazzo
OpenAPI Overlay Specification
Lanzada oficialmente en octubre, esta especificación permite aplicar cambios reutilizables a un documento OpenAPI. ¿Qué tipo de cambios?
- Mejorar descripciones de endpoints o parámetros.
- Agregar paginación a todos los
GET. - Eliminar operaciones obsoletas.
- Añadir extensiones específicas para herramientas o SDKs.
¿Lo mejor? Puedes aplicar estas acciones de forma automática a uno o varios archivos OpenAPI. Por ejemplo, este Overlay agrega una licencia MIT al documento:
overlay: 1.0.0
info:
title: Add MIT license
version: 1.0.0
actions:
- target: '$.info'
update:
license:
name: MIT
url: https://opensource.org/licenses/MIT
Esto viene de maravilla en entornos code-first, donde el archivo OpenAPI se genera desde el código y luego se sobrescribe. Con Overlay, puedes aplicar los mismos ajustes una y otra vez, de forma automática y limpia.
Ya hay herramientas compatibles como los CLIs de Speakeasy y Bump.sh, y en el repo oficial de Overlays hay más ejemplos listos para usar.
OpenAPI Arazzo Specification
Arazzo fue publicada en mayo de 2024, pero recibió su primer update (v1.0.1) en enero de este año. ¿Qué hace Arazzo? Permite describir secuencias de llamadas a APIs, encadenadas como un flujo de trabajo.
Sí, algo así como un storyboard de tu API: cada paso es una llamada, con sus condiciones de éxito y si se cumple, pasa al siguiente paso.
Esto sirve para:
- Crear documentación interactiva paso a paso.
- Generar SDKs con funciones que encapsulan múltiples llamadas.
- Testear flujos realistas de una API.
Aunque el tooling aún está en pañales, Spectral y Redocly CLI ya soportan Arazzo para linting, y se espera que muchos más lo integren en 2025.
Actualizaciones a OpenAPI 3.x
Aunque la versión 3.1.1 (lanzada en octubre) es un patch menor, representa la primera actualización desde 2021. ¡Buenas noticias! El proyecto sigue activo y en crecimiento.
¿Qué trajo esta versión?
- Mejoras en redacción y ejemplos.
- Nuevos apéndices para organización.
- Introducción actualizada.
- Mejor guía sobre parsing, tipos de datos y serialización.
- Actualización de los esquemas JSON oficiales.
También se actualizó la versión 3.0 a la 3.0.4 con cambios similares.
Lo Que Viene en el Camino
Versión 3.2 (Próximamente)
La próxima gran parada será la versión 3.2, que incluirá:
- Nuevos esquemas de seguridad.
- Funcionalidad ampliada para etiquetas (tags).
- Más mejoras y ajustes finos.
OpenAPI 4.0: Proyecto Moonwalk
Apenas está en fase de ideas, pero ya tiene nombre clave: Moonwalk. Esta versión representará un salto importante, aunque aún no hay fecha definida.
Participa en la Comunidad
OpenAPI es un estándar abierto, mantenido por la comunidad. Puedes contribuir con ideas, código o simplemente seguir los avances. Hay reuniones abiertas, Slack activo, y todos los repos están en GitHub. Checa openapis.org para sumarte.
Conclusión
- Overlay te deja automatizar ajustes en tus specs OpenAPI sin tocar el original.
- Arazzo conecta múltiples llamadas API en flujos complejos.
- La spec 3.1.1 trae orden y claridad.
- Se viene la 3.2 y un futuro Moonwalk 4.0.
Si trabajas con APIs, este es el momento de subirte al tren y prepararte para la era de APIs más limpias, reutilizables y entendibles para humanos, máquinas y hasta agentes de IA.