Documenta tus microservicios SpringBoot con SpringFox.

A la hora de diseñar un microservicio que va a ser consumido por otras aplicaciones, ya sean Front, otros Backends o incluso aplicaciones móviles, lo más habitual hoy en día es usar un API REST para realizar el intercambio de datos, usando JSON como formato.

Este sistema facilita mucho la integración entre sistemas, pero no debemos olvidarnos que detrás de un sistema existe una persona encargada de realizar dicha integración. Para facilitar la integración con un sistema que “habla” REST, existen diversos estándares: Swagger, RAML o JSONAPI, que proveen de una interfaz “human readable” para que los desarrolladores puedan implementar de forma más fácil y eficaz dichas integraciones.

En este post vamos a ver cómo documentar el API REST usando Java como lenguaje de programación, Spring (con su módulo SpringBoot para exponer el API) y SpringFox, una librería que ofrece tanto el documento de especificación Swagger como una interfaz web para entender (incluso probar) el API REST.

En primer lugar, iremos a la página de Spring Initializer para generar el esqueleto de nuestro microservicio con SpringBoot:

Seleccionamos la dependencia Web y haremos clic en Generate project para descargar el esqueleto, que importaremos como proyecto Maven en el IDE que usemos.

Una vez importado el proyecto, la estructura que tendremos será la siguiente:

He renombrado el fichero de propiedades a aplication.yml. Además, hemos reutilizado el controller, bean, service y repository, podéis ver cómo se hace en este post, y consultar y descargar las clases de este repositorio.

NOTA: La implementación del repository la he modificado para “mockear” los métodos y así no incorporar la dependencia de Mongo.

Una vez incorporados estos componentes, la estructura del proyecto sería:

A modo de recordatorio, el servicio expone dos operaciones REST:

• GET /api/person/{id}: para consultar una persona por su identificador.
• POST /api/person: para insertar una nueva persona.

El objetivo es contar con una documentación del API REST que cumpla la especificación 2.0 de Swagger, y además con una interfaz web amigable que nos permita entender y probar dicho API REST.

Para incluir SpringFox, lo primero que haremos será incluir las dependencias de SpringFox y del UI en nuestro pom de Maven:

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.6.1</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.6.1</version>
</dependency>

Después, editaremos la clase de arranque del SpringBoot para incluir los siguientes elementos:

1. La anotación @EnableSwagger2 en la cabecera de la clase:```
2. java
3. <br />
4. @SpringBootApplication<br />
5. @EnableSwagger2<br />
6. public class SpringbootSpringfoxApplication {<br />

2. La inyección por dependencia de la clase **TypeResolver** de fasterxml:```
java
<br />
@Autowired<br />
private TypeResolver typeResolver;<br />

3. La inyección por valor de la propiedad app.version definida en el fichero application.yml con el valor de la versión establecida en el pom:

• Fichero application.yml:```
  python" gutter="”true”
  <br />
  app:<br />
  version: '@pom.version@'<br />

- **Inyección**:
- ```
- java
- <br />
- @Value("${app.version}")<br />
- private String appVersion;<br />
- 
- ```
- El método anotado con **@Bean** que devuelve un objeto Docket y que configura el API con Swagger: ```
- java
- <br />
- @Bean<br />
- public Docket swaggerApi() {<br />
- return new Docket(DocumentationType.SWAGGER_2)<br />
- .select()<br />
- .apis(RequestHandlerSelectors<br />
- .basePackage("com.isolisduran.springboot.controller"))<br />
- .paths(PathSelectors.regex("/api/.*"))<br />
- .build()<br />
- .pathMapping("/")<br />
- .genericModelSubstitutes(ResponseEntity.class)<br />
- .alternateTypeRules(AlternateTypeRules.newRule(<br />
- typeResolver.resolve(DeferredResult.class,<br />
- typeResolver.resolve(ResponseEntity.class,WildcardType.class)),<br />
- typeResolver.resolve(WildcardType.class)))<br />
- .useDefaultResponseMessages(false)<br />
- .apiInfo(apiInfo());<br />
- }<br />
- 
- ```
- Aunque la configuración de Swagger con SpringFox permite muchas más opciones, hemos dejado las más básicas para entender su funcionamiento. Lo más relevante de este método es:
- · Establece qué paquete del proyecto contiene los controllers que se expondrán en el API:
- ```
- java
- <br />
- basePackage("com.isolisduran.springboot.controller")<br />
- 
- ```
- · A su vez, solo expone los controllers que expongan el path indicado:
- ```
- java
- <br />
- PathSelectors.regex("/api/.*")<br />
- 
- ```
- El método **apiInfo()** para documentar los datos básicos del API:```
- java
- <br />
- private ApiInfo apiInfo() {<br />
- return new ApiInfo(<br />
- "API Title",<br />
- "API Description",<br />
- appVersion,<br />
- "urn:tos",<br />
- new Contact("Contact Name", "http://www.none.com", "test@test.com"),<br />
- "API License",<br />
- "http://www.api-license-url.com");<br />
- }<br />
- 
- ```
- Con estos simples cambios ya tendríamos una documentación básica de nuestro API REST. Para probarlo, compilamos con:
- ```
- console
- <br />
- $ mvn clean package<br />
- 
- ```
- Y ejecutamos el jar resultante con:
- ```
- console
- <br />
- $ java -jar target/springboot-springfox-0.0.1-SNAPSHOT.jar<br />
- 
- ```
- Con este comando arrancaremos el servidor en el puerto 8080 en nuestro entorno local para poder probar SpringFox. Abrimos un navegador y accedemos a la url local **https://www.paradigmadigital.com/v2/api-docs**. Veremos el JSON de Swagger:

<article class="block block-image  -inside-grid "><a href="https://www.paradigmadigital.com/wp-content/uploads/2017/03/4.png"target=""><img src="https://www.paradigmadigital.com/assets/img/defaults/lazy-load.svg"
        data-src="https://www.paradigmadigital.com/wp-content/uploads/2017/03/4.png"
        data-srcset="https://www.paradigmadigital.com/wp-content/uploads/2017/03/4.png 1920w,https://www.paradigmadigital.com/wp-content/uploads/2017/03/4.png 1280w,https://www.paradigmadigital.com/wp-content/uploads/2017/03/4.png 910w,https://www.paradigmadigital.com/wp-content/uploads/2017/03/4.png 455w"
        class="lazy-img"  
                sizes="(max-width: 767px) 80vw, 75vw"
                alt="" title="undefined"/></a></article>


A su vez, si accedemos a swagger-ui veremos la interfaz web del API REST:

<article class="block block-image  -inside-grid "><a href="https://www.paradigmadigital.com/wp-content/uploads/2017/03/5.png"target=""><img src="https://www.paradigmadigital.com/assets/img/defaults/lazy-load.svg"
        data-src="https://www.paradigmadigital.com/wp-content/uploads/2017/03/5.png"
        data-srcset="https://www.paradigmadigital.com/wp-content/uploads/2017/03/5.png 1920w,https://www.paradigmadigital.com/wp-content/uploads/2017/03/5.png 1280w,https://www.paradigmadigital.com/wp-content/uploads/2017/03/5.png 910w,https://www.paradigmadigital.com/wp-content/uploads/2017/03/5.png 455w"
        class="lazy-img"  
                sizes="(max-width: 767px) 80vw, 75vw"
                alt="" title="undefined"/></a></article>


Con esto tendríamos documentada de forma básica nuestro API REST, pero SpringFox ofrece más opciones para documentar nuestro API:

<h3 class="block block-header h--h20-175-500 left  ">Documentación de Controllers:</h3>

SpringFox permite documentar los Controllers de Spring usando anotaciones:

1. En el método GET añadiremos lo marcado en negrita:```
2. java
3. &amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
4. @ApiOperation(value="Get a person by id", notes="Provides an operation to get a Person object by its identifier")&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
5. @ApiResponses(value={&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
6. @ApiResponse(code=200, message="OK", response=Person.class),&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
7. @ApiResponse(code=404, message="Not Found", response=String.class),&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
8. @ApiResponse(code=500, message="Internal Server Error", response=String.class)&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
9. })&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
10. @RequestMapping(method = RequestMethod.GET, value = "/person/{tiged}", produces = MediaType.APPLICATION_JSON_VALUE)&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
11. public @ResponseBody ResponseEntity&amp;amp;amp;amp;amp;lt;Person&amp;amp;amp;amp;amp;gt; getById(@ApiParam(value="Person identifier", required=true) @PathVariable int id) {&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
12. Person person = personService.getById(id);&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
13. return new ResponseEntity&amp;amp;amp;amp;amp;lt;&amp;amp;amp;amp;amp;gt;(person, HttpStatus.OK);&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;
14. }&amp;amp;amp;amp;amp;lt;br /&amp;amp;amp;amp;amp;gt;

2. En el método POST añadiremos igualmente lo marcado en negrita:```
   java
   <br />
   @ApiOperation(value="Create a new Person", notes="Provides an operation to create a new Person object and return its identifier")<br />
   @ApiResponses(value={<br />
   @ApiResponse(code=201, message="Created", response=String.class),<br />
   @ApiResponse(code=400, message="Bad Request", response=String.class),<br />
   @ApiResponse(code=500, message="Internal Server Error", response=String.class)<br />
   })<br />
   @RequestMapping(method = RequestMethod.POST, value = "/person", produces = MediaType.TEXT_PLAIN_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)<br />
   public @ResponseBody ResponseEntity<String> create(@ApiParam(value="JSON with Person to create", required=true) @Valid @RequestBody Person person) {<br />
   String newPersonId = String.valueOf(personService.create(person).getId());<br />
   return new ResponseEntity<String>(newPersonId, HttpStatus.CREATED);<br />
   }<br />

**NOTA**: Las anotaciones anteriores son específicas de Swagger y son provistas por la dependencia que SpringFox tiene de Swagger.

<h3 class="block block-header h--h20-175-500 left  ">Documentación de Beans:</h3>

El la clase Person incluiremos las siguientes anotaciones:

```undefined
java
<br />
@ApiModelProperty(value="Person identifier", required=true, example="1", position=1)<br />
private int id;<br />
@ApiModelProperty(value="Person name", required=true, example="MyName", position=2)<br />
private String name;<br />
@ApiModelProperty(value="Person address", required=false, example="MyName", position=3)<br />
private String address;<br />

% block:blockquote
% items:
% text:NOTA: Al igual que en el caso del controller, las anotaciones anteriores son específicas de Swagger y son provistas por la dependencia que SpringFox tiene de Swagger.
% endblock

Una vez hemos incluido estas anotaciones, compilamos de nuevo el proyecto con mvn clean package, ejecutamos de nuevo con java -jar para arrancar y probar el servicio en nuestro entorno local, y recargamos la url local en nuestro navegador:

Documentación del Get:

Documentación del Post:

Como podemos observar, con las anotaciones incluidas, tenemos una documentación más rica, con descripciones de los atributos de métodos y objetos, explicación de cada operación y resultados esperados en caso de éxito y error.

Además, como podemos observar, podemos probar interactivamente las operaciones expuestas en el API:

Ejecución del Get:

Ejecución del Post:

SpringFox nos proporciona de forma muy amigable la posibilidad de documentar nuestra API REST sin tener que generar la documentación nosotros mismos a mano.

A la vez que escribimos el código podemos documentar también el API, con lo que siempre tendremos control sobre los cambios introducidos. Además, al incluir el UI, facilita también la integración y pruebas por parte de las aplicaciones consumidoras.

Podéis encontrar el código de ejemplo en el repositorio de GitHub de Paradigma.