Ventajas de la adopción del estándar OpenAPI

Las ventajas de seguir el estándar OpenAPI en los proyectos que implican implementaciones de las APIs son múltiples: nos permite detectar posibles fallos en la fase temprana de definición, agilizar el proceso de desarrollo e implementación, ejecución de pruebas y elaboración de la documentación, haciendo hincapié en la cooperación de distintos departamentos implicados como, por ejemplo, frontend, backend y calidad. Y, por supuesto, lo que resulta esencial: nos permite finalmente ofrecer a nuestros clientes la entrega de un producto que no solo cumple con los estándares sino que también cubre sus necesidades de negocio.

El estándar OpenAPI comienza el ciclo de desarrollo por la definición y nos aporta siguientes ventajas:

• Facilita el diseño de la API gracias a las herramientas que existen para ello, proporcionando una estructura bien definida a seguir que vela por el cumplimiento del estándar.
• Permite centrarnos en las necesidades del consumidor de la API, abstrayéndose de los problemas que puedan surgir durante el desarrollo.
• Existen múltiples herramientas que nos permiten generar el código fuente de clientes/servidores de APIs a partir de su diseño, la documentación de una API ya implementada, la posibilidad de validar la estructura del diseño de la API o de realizar pruebas durante el desarrollo, entre otras tantas opciones.
• Reduce la dependencia entre los equipos que tienen que trabajar en la implementación de la API y permite comenzar con antelación los trabajos de estos al conocerse desde un principio la funcionalidad de la API.
• Debido a la eliminación de la dependencia entre equipos, el tiempo de implementación de la API es más reducido.

Implementación de la API siguiendo el estándar OpenAPI

Para aprovechar correctamente las ventajas del uso de estándar de OpenAPI, se aconseja que el ciclo de desarrollo comience por la fase de diseño (Contract-First).

Esto significa que antes de empezar a construir la API, pensar en la lógica de negocio o centrarse en posibles errores o defectos, diseñaremos la interfaz de la API detallando posibles peticiones y respuestas.

Definición de la API

En este paso es donde se hará uso de las especificaciones propuestas por OpenAPI y se creará el documento en formato YAML o JSON que contendrá la definición de la API.

La definición de una API para OpenAPI en su versión 3.0 se compone de la siguiente estructura de objetos:

Con el objetivo de facilitar el diseño de la API, podemos hacer uso de Swagger Editor, descargando la herramienta o haciendo uso de su versión online.

Implementación de la API

Para la implementación se puede hacer uso de herramientas de generación de código como Swagger Codegen u OpenAPI Generator, que permiten generar el esqueleto de las aplicaciones (tanto clientes como servidor) a partir de la definición de la API y soportan multitud de lenguajes de programación.

Versionar la API

Después de implementar la API es muy probable que tenga que ser evolucionada en algún momento, habiendo consumidores cuyos procesos no pueden ser alterados o que quieran seguir consumiendo la versión anterior. Para ello es primordial llevar un correcto versionado de nuestra API desde el comienzo de su implementación para así no ser disruptivos con futuros desarrollos.

La opción que conlleva un menor número de adaptaciones a realizar es la de incluir la versión de la API en el tipo de contenido de la cabecera como un valor concatenado de la misma. De este modo, los consumidores tendrán que especificar en la cabecera de la petición este parámetro y serán redirigidos a la versión que deseen consumir, sin tener que duplicar las URLs de los recursos a publicar.

Pruebas durante el desarrollo de la API

Implementar la API siguiendo las especificaciones propuestas por OpenAPI también facilita las tareas de pruebas y testing.

A partir de la definición realizada en el fichero YAML o JSON, es posible usar Swagger Inspector o SOAP-UI como herramientas de testing de la API.

Si tenemos incluidas las dependencias springfox-swagger y springfox-swagger-ui, podríamos probar nuestras implementaciones desde el navegador poniendo: <URL de la API>/swagger-ui.html.

Testing (unitario, de integración, automatizable)

Este punto consistiría en verificar la implementación de la API desarrollada dentro de un flujo de Integración Continua (CI) mediante distintas fases de testing, según aplique en cada caso.

Se recomienda integrar en Jenkins la automatización de los tests y herramientas que lo facilitan, pueden ser SOAP-UI o Postman, que disponen de plugins o ya vienen integrados, para aprovechar las pruebas generadas en el paso anterior.