“Java y Servicios REST: Autodocumentación al alcance de todos”

Si has desarrollado alguna vez un API de servicios REST que exponen funcionalidad para otras aplicaciones (una típica arquitectura de microservicios) es muy probable que te hayas visto en la situación de tener que documentar todas las llamadas para que terceros puedan integrarse sin necesidad de que estés presente para guiarles.

Documentar, en general, es una tarea generalmente tediosa y que no se suele hacerse según se va desarrollando. Más bien se va dejando para el final, cuando la entrega está a la vista, dando lugar a documentación escasa y poco útil. Además, en lo referente a microservicios, aunque existen muchos posts de buenas practicas para documentarlos, generalmente se acaba con un excel o word más o menos vistoso pero poco práctico.

Yo me pregunto entonces…¿No sería mejor que los microservicios se autodocumentasen? Esta misma pregunta se la han hecho los chicos de Springfox y Swagger y le han dado solución. Utilizando sus librerías, siempre y cuando utilicemos Java y Servicios REST, podemos automatizar la generación de documentación y ahorrar un tiempo que, podríamos invertir en mejorar la cobertura de tests.

Como ejemplo, vamos a documentar unos servicios REST ya existentes expuestos por una aplicación creada con Spring Booty partimos de:

  1. GET /api/stuff/{id}: Consulta de “cosas”
  2. POST /api/stuff: Obtención de “cosas” por su identificador

El primer paso es agregar las dependencias de Springfox y Swagger al proyecto. Si utilizamos Maven, podemos acudir al repositorio central para obtener la última versión:

Para habilitar el framework, utilizamos la anotación @EnableSwagger2 en una clase de configuración de Spring con el siguiente contenido:

La configuración mínima sería:

  • Utilizar la anotación @EnableSwagger2 en la cabecera de la clase
  • Crear un @Bean que devuelve un objeto Docket y que configura el API con Swagger
  • Establecer en la instancia del objeto Docket el package donde se encuentran nuestros servicios REST:

  • Indicar a la misma instancia Docket qué servicios vamos a exponer:

  • Crear un objeto ApiInfo con la información corporativa:

Con ello tendríamos la documentación básica para nuestro API de Servicios REST, compilamos e iniciamos la aplicación web. SpringBoot utiliza un servidor embebido para generar un war autoejecutable. Si no es el caso, podemos desplegar la aplicación en cualquier servidor de aplicaciones.

Si todo ha ido correctamente, suponiendo que tenemos desplegada la aplicación en localhost:8080, tenemos accesible la URL http://localhost:8080/v2/api-docs que muestra el JSON de configuración de Swagger, que no resulta especialmente útil como documentación. Sin embargo, si accedemos a http://localhost:8080/swagger-ui.html accedemos la la interfaz web de nuestros servicios:

Ya tendríamos documentada de forma básica nuestra API y de forma accesible a todo el que necesite utilizar nuestros servicios. Además, podemos probar los servicios expuestos de forma interactiva:

Si la documentación autogenerada no os parece suficiente, podemos hilar más fino poniendo un poco de esfuerzo por nuestra parte, SpringFox provee diversas anotaciones que podemos utilizar para documentar nuestros controladores, y DTOs (data-transfer objects):

  • Controladores: Utilizamos las anotaciones @ApiOperation, @ApiResponse y @ApiParam

  • Beans y DTOs: Utilizamos las antotaciones @ApiModelProperty

Compilamos y volvemos a iniciar la aplicación. Ahora nuestra interfaz web es mucho más detallada:

 

Como hemos visto, SpringFox provee los mecanismos que analizan las clases de la aplicación para obtener información de los Servicios REST. Con Swagger, generamos la interfaz gráfica que nos permite visualizar e interaccionar con ellos.

Como conclusión, podemos ver que la configuración de Swagger con SpringFox permite configuraciones mucho más completas de la mostrada en éste post, además, para finalizar os dejo ver todas las posibilidades en las web oficiales:

Springfox: https://springfox.github.io/springfox/docs/current/

Swagger: https://swagger.io/tools/swagger-ui/

 

 

Ingeniero en Informática de Sistemas por la Universidad Politécnica de Madrid, vive en el mundo del desarrollo de aplicaciones desde que cayó en sus manos un Spectrum. Especializado en Backend Java, sus días transcurren entre frameworks, arquitecturas y microservicios. Desconecta practicando fotografía y deportes de montaña (rutas, Snowboarding... lo que proceda según la época). Actualmente, trabaja como Designer en Future Space.