Como parte de las funciones de Arquitectura y DEVOPs hemos definido un proceso que nos permitirá hacer más accesible la documentación de las APIs de los microservicios del Laboratorio Digital y exponerla en los repositorios para que esté al alcance de todo el equipo de desarrollo. De esta manera podremos conocer los endpoints que expone un servicio, los parámetros que recibe y las respuestas que entrega.
Hemos implementado esta funcionalidad en cuatro servicios para que puedan servir como referencia:
Pero, ¿cómo funciona?
En los servicios detallados, al revisar el Overview de los repositorios podemos observar que existe una nueva sección en el README.md: “OpenApi Documentation”.
En esta sección se encuentran dos links:
- OpenAPI AWS Link: Enlace que nos redirige al swagger propio del microservicio. Por ejemplo: adapter-biometrics
- OpenAPI: Enlace que nos redirige a la documentación de la API dentro del mismo repositorio. Por ejemplo:
Ahora, ¿cómo lo implemento?
Para conseguir esta funcionalidad, se requiere que el equipo de desarrollo documente las APIs que se crean en los microservicios. En JAVA-Quarkus la documentación se realiza utilizando las anotaciones respectivas de OpenAPI que vienen en la librería “quarkus-smallrye-openapi”. Además, no olvidar que en el “application.properties” las configuraciones de swagger tienen que estar habilitadas:
- quarkus.swagger-ui.path=/swagger
- quarkus.swagger-ui.always-include=true
- quarkus.smallrye-openapi.path=/openapi.json
Queremos tener un alto nivel de detalle en el swagger, para ello tomar las siguientes consideraciones:
Ok, y todo esto ¿para qué?
Todo esto nos permitirá dar un paso más en la necesidad de disponibilizar la información y documentación de los servicios que como Laboratorio Digital implementamos para nuestra estructura tecnológica y que esté al alcance de todo el equipo. Recordemos que como parte de las buenas prácticas de desarrollo es responsabilidad de todo el equipo documentar los algoritmos y APIs de los servicios que creamos.
¿Qué se viene?
Como Arquitectura y DEVOPs continuamos mejorando este proceso para alcanzar la automatización necesaria y así poder expandirla a todos los microservicios. Pronto les estaremos comunicando los avances.
