Documentar proyecto JAX-RS con Swagger-Core y Swagger UI

 

link del proyecto: https://github.com/Francisco-Castillo/countries

Agregar dependencia en pom.xml

Para poder documentar nuestros proyectos API REST desarollados con JAX-RS, debemos utilizar la herramienta swagger-core. Para ello, es necesario incluir sus dependencias en el archivo pom.xml:

Agregar recursos en clase JAXRSConfig.java

Una vez agregada la dependencia, debemos incluir en la clase que se encarga de publicar el servicio REST, que en este caso se llama JAXRSConfig (podría ser cualquier otro nombre), los recursos que necesita swagger para poder iniciar:

• resources.add(io.swagger.jaxrs.listing.ApiListingResource.class)
• resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class)

Agregar clase Bootstrap.java

Como la documentación que generemos sera visualizada mediante una interfaz gráfica, debemos crear un servlet para poder configurar swagger. El objeto "swagger" establece mediante su método "basePath" la ruta o el "punto de entrada" a nuestra api, que en este caso es "countries/api". Usted debe reemplazar esto por los valores que correspondan en su caso.

Agregar anotaciones

Una vez agregada la dependencia, debemos incluir las anotaciones que nos permitan describir los recursos, las operaciones, parámetros, respuestas y modelos de nuestra API. 

Algunas de las anotaciones que se suelen utilizar son las siguientes:

• @Api
• @ApiOperation
• @ApiResponses
• @ApiResponse
• @ApiParam
• @ApiImplicitParams
• @ApiImplicitParam

@Api

Aplica a nivel de clase y se utiliza para denotar que dicha clase es un recurso para Swagger. A continuación se observa como aplicarla:

 

@ApiOperation

Esta anotación aplica a nivel de método, y se utiliza para incluir una explicación acerca de cual es la tarea que realiza dicho método.

@ApiResponses y @ApiResponse

Estas anotaciones se utilizan para describir cuales son las posibles respuestas que el metido podría producir. Por ejemplo, en una operación de inserción de productos puede ocurrir que el producto se inserte correctamente y en ese caso se debería producir una respuesta HTTP con un código de estado 201 y y el mensaje "Producto insertado correctamente", o bien podría ocurrir que el producto ya se encuentre en la base de datos, por lo que se podría retornar una respuesta incluyendo el código HTTP 209 y el mensaje de "Producto existente", entre otras. En el caso de retornar una sola respuesta se debe utilizar la anotación @ApiResponse, en caso de ser mas de una, usar @ApiResponse y en su interior incluir cada respuesta usando @ApiResponse.

@ApiParam

Se utiliza para describir los parámetros que espera recibir un método indicando su nombre, su tipo dato, si es requerido o no, entre otros. Esta anotación se debe incluir por cada parámetro que el método contenga.

A continuación se observa un ejemplo que incluye todas las anotaciones vistas hasta el momento:

@ApiImplicitParams y @ApiImplicitParam 

 Estas anotaciones se utilizan para indicar que un metodo puede recibir o no una serie de parametros. Generalmente se las suele utilizar en métodos que permiten realizar búsquedas. Al igual que en el caso de las respuestas, si el método espera recibir un solo parametro se debe utilizar @ApiImplicitParam, caso contrario utilizar @ApiImplicitParams, como se observa a continuacion:

Para conocer mas sobre las anotaciones, usted puede ingresar al siguiente enlace: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X

Agregar Swagger UI

El último paso, consiste en agregar la interfaz grafica de swagger, la cual esta disponible en el siguiente enlace: https://github.com/swagger-api/swagger-ui

Una vez clonada o descargada, se debe ingresar en la carpeta "diste" y copiar todos los dentro del directorio "Web Pages" de nuestro proyecto, quedando de la siguiente manera:

Una vez agregados los archivos, debemos editar "index.html", para colocar la ruta completa en donde se encuentra el archivo llamado "swagger.json" que es el que contiene la documentacion de nuestra API. Por defecto, la variable llamada "url", contiene un string hardcodeado a una url de prueba hacia swagger, el cual debe ser reemplazado por la dirección de nuestro proyecto que en este caso es: http://localhost:8080/countries/api/swagger.json, o bien obtenerlo de manera dinamica mediante la variable "apiUrl"

Luego debemos limpiar, construir y ejecutar el proyecto, como resultado obtendremos la visualización del archivo index.html publicado en: http://localhost:8080/countries