Uno de los problemas comunes al desarrollar software es la documentación, sobre todo cuando se desarrolla servicios web RESTful y el desarrollador no tuvo la “delicadeza” de describir con algo de detalle la forma de consumir los servicios desarrollados.

En este caso, se ejemplifica una forma muy sencilla de documentar servicios RESTful desarrollados en Java con Spring Boot utilizando SWAGGER2.

Para este ejemplo, se utilizó:

• NetBeans IDE 8.2
• Java 1.8
• Spring Boot 2.0
• Maven 3.0.5

En el archivo pom.xml es importante agregar las dependencias para usar SWAGGER:

<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>

En el proyecto, es requerido agregar una clase para configurar SWAGGER, en este caso se agrega la siguiente clase y configuración:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.shc.restful.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

}

Es recomendable definir en la configuración el paquete donde se encuentran los “controllers” para que en la vista web solo se muestren los servicios que se exponen a través de estos. Para lo anterior, usamos basePackage para establecer la ruta de las clases.

El código usado para este post lo pueden descargar en: https://github.com/saulhuerta/swagger2-example

En el caso de que descargaras el proyecto, lo puedes compilar y ejecutar, por lo que en tu navegador deberás ingresar en la siguiente dirección: localhost:8080/swagger-ui.html

Si todo se ejecutó de forma correcta e ingresas a la URL anterior, se deberá mostrar algo como en la siguiente imagen:

Es posible seleccionar algún método y se mostrará el detalle como los tipos de dato, parámetros e incluso la forma de como consumir dicho servicio con CURL, tal como se muestra a continuación:

Con lo anterior te puedo comentar que es muy sencillo documentar tus servicios RESTful desarrollados con Spring Boot y te aseguro que los desarrolladores que sean los clientes de tus servicios te lo agradecerán.

Saludos