Configurar Swagger para documentar un API REST en Spring Boot

La buena experiencia del usuario es clave para usar cualquier producto, y lo mismo ocurre con las API. Cuanto mejor sea la interfaz que se utiliza para consumir API, mayores serán las posibilidades de lograr sus objetivos comerciales y tecnológicos.

¿Por qué es importante la documentación?

Es una de las piezas básicas que determinan la experiencia de un desarrollador al hacer uso de tus servicios API, y va más allá del formato de respuesta API o el método de autentificación .La documentación debe ser interactiva, mostrando a los desarrolladores la estructura y la organización que les facilitará el trabajo, de modo que no tengan que pasar tiempo investigando las funciones o perderlo en pruebas totalmente improductivas.

Primer paso: Incluir las dependencias.

Nuestras dependencias las debemos incluir dentro del archivo principal del proyecto de Spring.

Para un proyecto maven ve al archivo poom.xml y agrega las siguientes lineas:

       <dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
       </dependency>

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

Si estás utilizando Gradle ve al archivo build.gradle y agrega las siguientes lineas:

implementation 'io.springfox:springfox-swagger2:2.9.2'

implementation 'io.springfox:springfox-swagger-ui:2.9.2'

Siguiente paso: Crear la configuración.

Vamos a crear una nueva clase con el nombre SwaggerConfig. La configuración de Swagger se centra principalmente en el bean Docket.

Agregamos las anotaciones de configuración y la libreria de Swagger2:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

Construimos el bean que va a retornar el Docket (spring fox documentation) .

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ejemplo.web.controller"))
                .build();
    }
}

Después de definir el bean Docket , su método select () devuelve una instancia de ApiSelectorBuilder, que proporciona una forma de controlar los puntos finales expuestos por Swagger. Dentro del método apis() agregamos el path que apunta a nuestros Controller que contienen los servicios expuestos.

Vamos a verificar

Para este momento ya podríamos verificar que Springfox está funcionando, podemos visitar esta URL en nuestro navegador:

http: // localhost: 8080 / spring-security-rest / api / swagger-ui.html

El resultado debería verse así:

Como se observa en las imagenes anteriores ya podemos ver cada uno de los métodos implementados en nuestro proyecto, e incluso nos da ejemplos de lo que se espera que reciba y responda cada uno de ellos. Podemos ver que Springfox ha generado las especificaciones para la entidad Product con métodos HTTP como GET , POST, PUT, PATCH y DELETE. Swagger también nos provee un pequeño cliente donde podemos probar y ejecutar las peticiones, facilitando las pruebas de los métodos expuestos.

Bonus: Modificando las vistas de Swagger

Podemos personalizar las vistas de nuestros métodos desde cada Controller, veamos.

@RestController
@RequestMapping("/products")
public class ProductController {
    @Autowired
    private ProductService productService;

    @GetMapping("/all")
    @ApiOperation("Get all supermarket products")
    @ApiResponse(code = 200, message = "OK")
    public ResponseEntity<List<Product>> getAll() {
        return new ResponseEntity<>(productService.getAll(), HttpStatus.OK);
    }

    @GetMapping("/{id}")
    @ApiOperation("Search a product with an ID")
    @ApiResponses({
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 404, message = "Product not found"),
    })
    public ResponseEntity<Product> getProduct(@PathVariable("id") int productId) {
        return productService.getProduct(productId)
                .map(product -> new ResponseEntity<>(product, HttpStatus.OK))
                .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
    }
	
}

La anotación de @ApiOperation nos permite agregar una descripción al método expuesto en Swagger y la @ApiResponse nos permite modificar los mensajes de respuesta del servicio según el estatus HTTP.

Con esto la documentación de nuestra API debería cambiar, el resultado debería ser el siguiente:

Vemos como cada método tiene una pequeña descripción adelante que fue añadida desde el Controller con el @ApiOperation, además observamos que las respuestas del método han sido personalizadas.

Conclusión

En este artículo, configuramos Swagger 2 para generar documentación para una API REST de Spring boot. También exploramos formas de visualizar y personalizar la salida de Swagger.