Desde tiempos inmemorables, los estándares ayudan a proporcionar un marco común de comunicación y desarrollo, y permiten elegir las herramientas adecuadas en función de una necesidad específica.

Por ello, a la hora de realizar las implementaciones de APIs, en ALTEN seguimos el estándar OpenAPI (OAS), que es el estándar para la definición de API por excelencia, siendo agnóstico en cuanto al lenguaje se refiere, y que establece un marco común para diseñadores, desarrolladores y testers sobre cómo construir y mantener las APIs. En este post veremos estos y otros beneficios adicionales de usar el estándar.

Ventajas del ciclo de desarrollo del estándar OpenAPI

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.

A continuación, detallamos cómo proceder con el desarrollo de la API partiendo de su definición y te aconsejamos el uso de determinadas herramientas que facilitarán la tarea.

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.

Documentando la API con Swagger-UI en Spring Boot

Puede darse el caso de que tengamos desarrollada la API y no esté documentada. En este caso, aconsejamos una forma sencilla de publicar la interfaz de Swagger de nuestra aplicación que nos asegura exponer las definiciones de las API.

1. Lo primero que debemos hacer es incluir en el pom.xml de nuestro proyecto siguientes dependencias:

            io.springfox
            springfox-swagger2
            ${swagger.version}
        

        
            io.springfox
            springfox-swagger-ui
            ${swagger.version}
        

1. El parámetro swagger.version tiene que ser compatible con las versiones de dependencias de Spring y de Java.
2. Implementar una clase Java que habilite Swagger y “descubra” la información existente sobre las APIs implementadas en nuestro proyecto. Un ejemplo del formato de esa clase Java sería:

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public LinkDiscoverers discoverers() {
        List plugins = new ArrayList<>();
        plugins.add(new CollectionJsonLinkDiscoverer());
        return new LinkDiscoverers(SimplePluginRegistry.create(plugins));
    }
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();
    }
}

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: /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.

Conclusiones

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.

Si te ha interesado el contenido de este post, no puedes perderte la píldora formativa que Nina Osipova compartió con nuestro equipo web:

 

Web Team
ALTEN