Cómo Implementar Swagger con Springdoc en Spring Boot

En el desarrollo de APIs modernas, la documentación es crucial para facilitar la comprensión y el uso eficiente de los servicios expuestos. Swagger (OpenAPI) es una de las herramientas más populares para documentar y diseñar APIs REST de manera visual y fácilmente comprensible. En este artículo, te mostraremos cómo integrar Swagger en una aplicación de Spring Boot utilizando Springdoc, específicamente con la versión springdoc-openapi-starter-webmvc-ui versión 2.0.3.

1. Agregar la Dependencia Springdoc

Para comenzar, debes agregar la dependencia de Springdoc a tu archivo pom.xml. Esta dependencia es responsable de integrar automáticamente Swagger 2 en tu aplicación Spring Boot. Aquí está el fragmento que necesitas incluir:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.3</version>
</dependency>

2. Configuración Básica

Una vez agregada la dependencia, la mayoría de la configuración de Swagger es automática. Springdoc escanea tus controladores y métodos de API, generando la documentación correspondiente. Sin embargo, puedes personalizar la configuración básica para reflejar detalles específicos de tu proyecto. Esto se hace generalmente en el archivo application.properties o application.yml de Spring. Aquí un ejemplo básico:

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

Estas propiedades cambian las rutas predeterminadas donde Springdoc expone los documentos de la API y la interfaz de usuario de Swagger.

3. Personalizar la Documentación de la API

Puedes mejorar la documentación generada añadiendo anotaciones específicas en tus controladores y métodos. Por ejemplo, usar @Operation(summary = "Descripción aquí") proporciona un resumen de lo que hace el método de la API. Las anotaciones como @Parameter, @ApiResponse, y @Tag también son útiles para proporcionar más detalles y claridad.

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "Obtiene un usuario por ID")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return ResponseEntity.ok(new User(id, "nombre", "correo@example.com"));
    }
}

4. Visualización de la Documentación

Para ver la documentación generada por Swagger, simplemente ejecuta tu aplicación Spring Boot y navega a http://localhost:8080/swagger-ui.html (ajusta el puerto según tu configuración). Esto te llevará a la interfaz de usuario de Swagger, donde podrás ver todos los endpoints de tu API, modelos de datos y realizar pruebas directamente desde el navegador.

5. Consideraciones de Seguridad

Es importante considerar aspectos de seguridad, especialmente si la documentación de Swagger está disponible en un entorno de producción. Puedes restringir el acceso a la interfaz de Swagger utilizando configuraciones de seguridad de Spring o configurando Spring Security para limitar el acceso solo a usuarios autorizados.

Conclusión

Integrar Swagger usando Springdoc en una aplicación Spring Boot es un proceso directo que mejora significativamente la experiencia del desarrollador. Con la documentación automática y la capacidad de personalización, puedes proporcionar una interfaz clara y útil para que los desarrolladores interactúen con tu API.