¿Cuál es la última versión de la especificación OpenAPI? #

La especificación OpenAPI (OAS) se ha consolidado como la piedra angular de la documentación, la estandarización y la aplicación de buenas prácticas en las API. Equipos de todo el mundo aprovechan OpenAPI para definir interfaces, automatizar procesos y garantizar la coherencia entre sistemas. A medida que las API siguen evolucionando, la especificación OpenAPI también debe avanzar para reflejar las nuevas necesidades y los avances tecnológicos. Entonces, ¿cuál es la última versión de la especificación OpenAPI y qué aporta?

La última versión: especificación OpenAPI 3.2.0 #

A 2026, la última versión de la especificación OpenAPI es la 3.2.0, publicada el 19 de septiembre de 2025. Es una versión menor, compatible con versiones anteriores, dentro de la línea 3.x (todo documento 3.0 o 3.1 válido sigue siendo válido bajo la 3.2), pero añade un conjunto considerable de nuevos campos y capacidades orientados a patrones modernos de API, como el streaming, un etiquetado más rico y flujos de autenticación adicionales.

Junto con la 3.2.0, la OpenAPI Initiative (OAI) publicó ese mismo día la 3.1.2 (un parche exclusivamente editorial de la línea 3.1, sin cambios materiales de comportamiento). El parche más reciente de la línea 3.0.x es la 3.0.4, publicada el 24 de octubre de 2024.

Principales novedades de OpenAPI 3.2.0 #

1. Etiquetas multipropósito y anidadas #

El objeto de etiqueta (Tag Object) incorpora un campo summary, un campo parent (para anidar etiquetas bajo otras etiquetas) y un campo kind para clasificar la finalidad de una etiqueta (por ejemplo, nav para agrupaciones de navegación frente a etiquetas que indican una audiencia). Un registro de tipos de etiqueta complementario establece valores convencionales para kind.

2. Métodos HTTP adicionales #

Además de los ya existentes get/post/put/delete/options/head/patch/trace, OAS 3.2 añade compatibilidad de primer nivel con el método query, así como un mapa additionalOperations en el objeto de elemento de ruta (Path Item Object) para cualquier otro método HTTP (como LINK) que no sea ya una clave con nombre.

3. Identidad del documento con $self #

Un nuevo campo $self de nivel superior permite que un documento declare su propio URI base, que se utiliza para resolver referencias relativas. Esto hace que los documentos OpenAPI se identifiquen a sí mismos, algo útil cuando un documento se divide en varios archivos o se sirve desde ubicaciones distintas.

4. Streaming y eventos enviados por el servidor (SSE) #

OAS 3.2 admite formalmente tipos de medios secuenciales como text/event-stream (SSE), multipart/mixed, application/jsonl y application/json-seq. Ahora una respuesta puede describirse como un flujo repetitivo de elementos mediante el nuevo campo itemSchema de un objeto de tipo de medio (Media Type Object).

responses:
  '200':
    description: A stream of stock price updates
    content:
      text/event-stream:
        itemSchema:
          $ref: '#/components/schemas/StockUpdate'

5. Ubicación de parámetro querystring y estilo de cookie #

Una nueva ubicación de parámetro, querystring, permite analizar toda la cadena de consulta como un único campo (mediante content), de forma similar a como se tratan los cuerpos de solicitud. También hay disponible un nuevo valor de style, cookie, para parámetros y encabezados, que coincide con el modo en que los navegadores dan formato a los valores de las cookies.

6. Mejoras en los tipos de medios multipart #

Los nuevos campos prefixEncoding e itemEncoding ofrecen un control más preciso de la codificación de los tipos de medios multipart, junto con el nuevo campo itemSchema para describir cada parte.

7. Modelado de XML con nodeType #

La palabra clave xml del objeto de esquema (Schema Object) incorpora un campo nodeType (element, attribute, text, cdata o none), que sustituye a los antiguos campos booleanos attribute y wrapped (ambos ahora obsoletos, aunque se siguen admitiendo por compatibilidad con versiones anteriores).

8. Ejemplos estructurados y serializados #

El objeto de ejemplo (Example Object) añade dataValue (el ejemplo en forma estructurada o nativa) y serializedValue (cómo se ve el ejemplo una vez serializado en la red), lo que ofrece una distinción más clara que la del campo único value anterior.

9. Mejoras en los esquemas de seguridad #

• Compatibilidad con el flujo de autorización de dispositivos de OAuth2, mediante un nuevo campo deviceAuthorizationUrl.
• Un nuevo campo oauth2MetadataUrl para apuntar a un documento de metadatos del servidor de autorización de OAuth2.
• Los esquemas de seguridad ahora pueden marcarse como deprecated y pueden referenciarse mediante un URI en lugar de declararse únicamente en línea bajo components.

10. Adiciones menores pero notables #

• El objeto de servidor (Server Object) incorpora un campo name, y la sustitución de variables en la URL del servidor cuenta ahora con una gramática ABNF formal.
• El propertyName del discriminador ahora es opcional, con un nuevo campo defaultMapping para el esquema de respaldo.
• El description de las respuestas ahora es opcional, y hay un nuevo campo summary disponible en las respuestas.
• Una nueva entrada mediaTypes bajo components permite definir objetos de tipo de medio reutilizables.

Cómo se relaciona la 3.2 con OpenAPI 4.0 («Moonwalk») #

Algunas de estas adiciones, en especial las mejoras de las etiquetas y el campo $self, se originaron como exploraciones de la iniciativa OpenAPI Moonwalk, el esfuerzo de la OAI por diseñar OpenAPI 4.0. Como eran compatibles con versiones anteriores, el grupo de trabajo las incorporó pronto a la línea 3.x en lugar de esperar a una futura versión principal. La propia Moonwalk/4.0 sigue en una fase de diseño activa y abierta, sin fecha de lanzamiento fija, por lo que la 3.2 es la versión que conviene adoptar hoy.

Migración desde versiones anteriores #

Actualizar de OAS 3.0.x o 3.1.x a la 3.2.0 es sencillo, ya que la 3.2 es totalmente compatible con versiones anteriores: ningún documento válido existente deja de serlo. Sin embargo, para aprovechar la nueva versión conviene revisar tu cadena de herramientas:

1. Comprueba la compatibilidad de las herramientas: confirma que tus analizadores, linters y generadores de código ya admiten la 3.2 antes de depender de campos exclusivos de la 3.2, como $self, itemSchema o additionalOperations.
2. Adopta la anidación de etiquetas de forma gradual: los nuevos campos de etiqueta parent/kind/summary son aditivos, por lo que puedes adoptarlos poco a poco sin reestructurar las etiquetas existentes.
3. Valora la compatibilidad con streaming: si tu API ya usa SSE o JSON delimitado por saltos de línea de manera informal, migrar esas respuestas para que usen itemSchema ofrece a los consumidores una estructura documentada formalmente.
4. Revisa los campos XML obsoletos: sustituye attribute: true y wrapped: true por el nuevo campo nodeType donde tus herramientas lo admitan.
5. Actualiza el campo openapi: establece openapi: 3.2.0 una vez que tu documento se haya validado con la nueva versión.

Herramientas y compatibilidad del ecosistema #

La compatibilidad de las herramientas con la 3.2.0 todavía se está desplegando en el ecosistema (como es habitual justo después de la publicación de una especificación), mientras que la compatibilidad con la 3.1.x y la 3.0.x es madura y universal:

• Swagger: Swagger Editor y Swagger UI admiten ampliamente OAS 3.0 y 3.1, y la compatibilidad con la 3.2 se va incorporando de forma gradual.
• Redocly CLI y ReDoc: siguen de cerca las nuevas versiones de OAS, incluidos los campos de la 3.2.
• Postman: admite la importación y el trabajo con definiciones OAS 3.0 y 3.1, y la compatibilidad con la 3.2 seguirá la curva de adopción de la especificación.

Como la 3.2 es aditiva, las herramientas que solo entienden la 3.0/3.1 normalmente seguirán manejando de forma razonable un documento 3.2 en los campos que reconocen, aunque sin las nuevas capacidades.

Conclusión #

La especificación OpenAPI 3.2.0 es la última versión actual: se apoya en la alineación completa de la 3.1 con JSON Schema y añade mejoras prácticas para las API de streaming, una organización de etiquetas más rica, documentos que se describen a sí mismos y flujos de autenticación ampliados, todo ello manteniendo la compatibilidad con los documentos 3.0.x y 3.1.x existentes. Mientras tanto, la iniciativa OpenAPI 4.0 («Moonwalk») continúa con su trabajo de rediseño a más largo plazo y sin plazos definidos, y algunas ideas seleccionadas se siguen incorporando a la línea 3.x siempre que es posible.

Para obtener más detalles sobre la especificación OpenAPI y las últimas novedades, visita la OpenAPI Initiative o consulta las notas de la versión en GitHub.

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