¿Cuáles son las características clave de la OpenAPI Specification 3.0? #

La OpenAPI Specification (OAS) 3.0 es una actualización significativa del estándar global para describir y consumir API. Dirigida por la OpenAPI Initiative, un proyecto de la Linux Foundation, la especificación ofrece un marco completo y maduro para diseñar, documentar y consumir API. Este artículo profundiza en las características clave y los beneficios de la OpenAPI Specification 3.0.

Introducción a la OpenAPI Specification #

La OpenAPI Specification es un formato independiente del lenguaje para describir API RESTful. Originalmente parte del ecosistema de Swagger, pasó a llamarse OpenAPI tras su donación a la Linux Foundation en 2015. Tanto las personas como las máquinas pueden comprender fácilmente las API REST descritas con la OAS e interactuar con ellas.

La OAS 3.0, publicada el 26 de julio de 2017, introduce mejoras significativas respecto a su predecesora (OAS 2.0 o Swagger 2.0), que hacen que el diseño y la documentación de API sean aún más robustos y fáciles de usar.

Características clave de la OpenAPI Specification 3.0 #

1. Estructura y legibilidad mejoradas #

Una de las mejoras más significativas de OpenAPI 3.0 es su estructura, diseñada para ser más intuitiva y legible. La gramática del documento se ha refinado para facilitar su comprensión y reducir la redundancia.

Ejemplos:

• La clave swagger se ha reemplazado por openapi, que ahora requiere un identificador de versión (3.0.x).
• Divide las secciones definitions, parameters, responses y securityDefinitions de OpenAPI 2.0 en componentes dentro del objeto components, lo que fomenta una mejor organización de estos componentes reutilizables.
• Introdujo las secciones paths y components para lograr una estructura de esquemas organizada.

2. Compatibilidad mejorada con JSON Schema #

OpenAPI 3.0 admite un subconjunto extendido de la especificación JSON Schema. Esto incluye:

• Compatibilidad con las características clave oneOf, anyOf y not, que permiten validaciones y definiciones de tipos más ricas y versátiles.
• La introducción del campo nullable para indicar directamente las propiedades que admiten valores nulos.
• La posibilidad de realizar composiciones complejas mediante allOf para manejar mejor la herencia y las interfaces.

3. Manejo mejorado de parámetros #

OpenAPI 3.0 introduce formas más claras y flexibles de definir parámetros en comparación con OpenAPI 2.0:

• Distingue entre los parámetros path, query, header y cookie mediante el campo in.
• Los campos name e in ahora son obligatorios, lo que reduce la posibilidad de interpretar mal un parámetro.
• Introduce el concepto de enrutamiento de objetos profundos (deep object) para los parámetros de consulta, lo que mejora el manejo de esquemas de consulta complejos.

4. Cuerpos de solicitud #

Una de las incorporaciones sustanciales de la OAS 3.0 es el objeto explícito requestBody. A diferencia de la OAS 2.0, que mezclaba los parámetros y los cuerpos de solicitud, la OAS 3.0 establece una distinción clara:

• El objeto requestBody puede definir el tipo de contenido (content) y la carga útil correspondiente (schema).
• Permite establecer descripciones y distintos ejemplos por tipo de medio, lo que lo hace muy versátil para documentar cargas útiles de solicitud en diversos formatos.

5. Respuestas mejoradas #

Las respuestas en OpenAPI 3.0 son más versátiles y fáciles de definir:

• El objeto responses ya no limita las descripciones a simples cadenas; ahora admite formatos de datos como objetos y arreglos (arrays).
• La palabra clave content permite a los usuarios definir uno o más tipos de medio para las cargas útiles de respuesta.
• Compatibilidad con links para indicar relaciones entre respuestas, lo que mejora la capacidad de descubrimiento de la API.

6. Callbacks #

La introducción de callbacks permite modelar API asíncronas. Los callbacks permiten definir solicitudes fuera de banda que una API puede necesitar realizar a servicios externos o a URL proporcionadas por el cliente:

• Pueden definir una serie de solicitudes desencadenadas por una solicitud inicial.
• Son útiles en API orientadas a eventos (como notificaciones o webhooks), donde a la respuesta de una solicitud inicial le siguen solicitudes de callback adicionales.

7. Esquemas de seguridad #

OpenAPI 3.0 amplía y refina las definiciones de seguridad:

• Incluye compatibilidad con la bearer authentication mediante el campo scheme: "bearer".
• Compatibilidad completa con la seguridad basada en OpenID Connect mediante el campo openIdConnectUrl.
• El campo scopes se integra de forma más limpia en los distintos tipos de esquemas de seguridad.

8. Negociación de contenido #

La compatibilidad con la negociación de contenido garantiza que una API pueda describir su capacidad para servir distintos tipos de datos:

• La palabra clave content, tanto en requestBody como en responses, admite múltiples tipos de medio.
• Cada tipo de medio puede tener su propio esquema, sus ejemplos y sus campos obligatorios u opcionales, lo que ayuda a crear definiciones de API más flexibles y reutilizables.

Características y mejoras adicionales #

Carga de archivos simplificada #

En la OAS 3.0, la carga de archivos es más sencilla:

• Cuando un parámetro se designa como in: "formData", el type: "file" de la OAS 3.0 queda obsoleto.
• En su lugar, el objeto content define el formato de los datos binarios, lo que aclara el manejo de los datos de formulario multipart y mejora la compatibilidad.

Componentes reutilizables #

La OAS 3.0 introduce una sección central components donde pueden definirse y reutilizarse elementos comunes de la API:

• Los esquemas, las respuestas, los parámetros, los ejemplos, los cuerpos de solicitud y los encabezados comunes pueden centralizarse para facilitar su reutilización, lo que fomenta los principios DRY (Don’t Repeat Yourself, no te repitas).
• Reduce la redundancia y la carga de mantenimiento al centralizar estos componentes.

Obsolescencia y extensiones #

La OAS 3.0 ofrece una mejor compatibilidad con los campos obsoletos y las extensiones:

• El campo deprecated está disponible de forma universal en las distintas partes de la especificación, lo que permite a quienes diseñan API marcar como obsoletas las rutas, las operaciones o los parámetros.
• La extensibilidad personalizada mediante las extensiones de proveedor x-* sigue siendo robusta y ofrece flexibilidad para diseños de API que requieren un manejo especial fuera del alcance del esquema principal.

Etiquetas y documentación #

La OAS 3.0 mejora la forma en que se documentan y categorizan las API:

• Las etiquetas ayudan a agrupar operaciones relacionadas, lo que mejora la legibilidad de las API de gran tamaño.
• Los arreglos (arrays) tags a nivel de operación ayudan a documentar operaciones con múltiples agrupaciones contextuales.

Links #

La característica de links permite definir relaciones entre operaciones:

• Los links pueden orientar a los consumidores de la API sobre cómo las respuestas de una operación pueden usarse como entradas de otra.
• Proporcionan trazas de los posibles recorridos del cliente a través de la API, lo que mejora el aspecto de datos enlazados para la navegación de la API.

Adopción #

Muchas empresas y plataformas han adoptado la OAS 3.0. Dada su amplia aceptación en la industria, las herramientas y las integraciones compatibles con la OAS 3.0 son cada vez más ubicuas. Algunas plataformas destacadas son:

• La familia de herramientas de Swagger de SmartBear.
• Postman, que integra directamente las especificaciones OpenAPI.
• ReDoc, una herramienta de código abierto para generar documentación de API a partir de definiciones de OpenAPI 3.0.
• Stoplight para el diseño, la documentación y la gobernanza de API.

Conclusión #

La OpenAPI Specification 3.0 aporta numerosas mejoras prácticas para diseñar y documentar API. Con una mayor legibilidad, una mejor estructura, una compatibilidad ampliada con JSON Schema, cuerpos de solicitud explícitos, definiciones de respuesta detalladas y más, la OAS 3.0 aborda muchos de los puntos débiles que enfrentaban los desarrolladores con las versiones anteriores de OpenAPI.

Estas mejoras no solo facilitan mejores prácticas de diseño de API, sino que también optimizan la experiencia general del desarrollador y resultan relevantes en una amplia gama de escenarios de aplicación, desde las API REST convencionales hasta arquitecturas más modernas orientadas a eventos y de microservicios.

Para una exploración detallada de la OAS 3.0, consulta la documentación oficial de la OpenAPI Specification.

Última actualización: 21 de mayo de 2024.