Documentación de APIs con Swagger en Spring Boot

¿Cómo documentar APIs con Swagger en un proyecto?

Documentar nuestras APIs es fundamental para ofrecer una interfaz profesional y robusta que facilite el acceso a quienes desean consumirla. Swagger es una herramienta poderosa que nos ayuda a lograr esto mediante anotaciones. En este artículo, aprenderás cómo implementar Swagger en tu proyecto y optimizar la documentación de tus servicios, haciendo que la presentación de tu API sea clara y accesible para los desarrolladores.

¿Cómo incluir las dependencias necesarias de Swagger?

El primer paso para usar Swagger en nuestro proyecto es incluir las dependencias adecuadas. Esto se hace editando el archivo build.gradle de la siguiente manera:

1. Buscar dependencias: Ingresa al Maven Repository y busca Swagger2.
2. Seleccionar versión: Busca una versión ampliamente utilizada, por ejemplo, 2.9.2.
3. Copiar el grupo: Pega el siguiente bloque en la sección de dependencias:

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

4. Cargar los cambios: No olvides hacer clic en el botón Load Gradle Changes para refrescar las dependencias en tu proyecto.

Al hacer estos pasos, integras Swagger2 en tu aplicación, listo para ser configurado y utilizado.

¿Cómo configurar Swagger en nuestra aplicación?

Después de incluir las dependencias, es momento de configurar Swagger para que comience a documentar nuestros endpoints. Sigue estos pasos:

1. Crear un paquete de configuración: Dentro del paquete principal (web), crea otro llamado config.
2. Configurar Swagger: En el paquete config, crea una clase llamada SwaggerConfig y anótala de la siguiente manera:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .build();
    }
}

3. Relanzar la aplicación: Una vez configurado, empuja la aplicación nuevamente y verifica en el navegador que Swagger está funcionando correctamente introduciendo /swagger-ui.html tras tu URL base.

Con esto, tus endpoints quedarán documentados y accesibles para otros desarrolladores.

¿Cómo mejorar la documentación visual y práctica de Swagger?

Para que tu API no solo sea funcional sino también visualmente descriptiva y precisa, puedes añadir anotaciones adicionales en tus controladores. Esto dicta cómo Swagger debe mostrar y estructurar la información de cada endpoint.

1. Añadir anotaciones en tu controlador:

   Al ProductController, agrega las siguientes anotaciones para detallar la operación del método getAll:

@ApiOperation(value = "Get all supermarket products", response = Product.class)
public ResponseEntity<List<Product>> getAll() {
    return service.getAll();
}

2. Documentar respuestas y parámetros:

   Si es necesario, describe las respuestas posibles y los parámetros de entrada, como con el método que busca un producto por su ID:

@ApiOperation("Search a product with an ID")
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "OK"),
    @ApiResponse(code = 404, message = "Product not found")
})
public ResponseEntity<Product> getProductById(
    @ApiParam(value = "The ID of the product", required = true, example = "7")
    @PathVariable("id") int productId) {
        return service.getProductById(productId);
}

3. Verificar cambios:

   Después de ajustar anotaciones y detalles, reinicia la aplicación y vuelve a comprobar que los cambios se reflejan en la interfaz de Swagger accesible desde el navegador.

Implementar Swagger te ayudará a comunicar de manera eficiente cómo interactuar con tu API, mejorando la experiencia del usuario y estableciendo un estándar profesional. Continúa explorando y optimizando cada recurso de tu aplicación. ¡El aprendizaje nunca termina!