Documentación de APIs con Swagger / OpenAPI

Cuando una API crece, es importante documentarla para que otros desarrolladores puedan entender cómo usarla.

En lugar de escribir documentación manualmente, podemos generar documentación automática.

La herramienta más utilizada para esto es:

Swagger (OpenAPI)

Swagger permite:

• ver todos los endpoints
• probar la API desde el navegador
• ver parámetros y respuestas
• entender cómo funciona la API

1. Qué es OpenAPI #

OpenAPI es un estándar para describir APIs.

Define:

• rutas
• métodos HTTP
• parámetros
• respuestas

Swagger es una herramienta que visualiza OpenAPI.

2. Dependencia para Spring Boot #

En Spring Boot moderno se usa SpringDoc OpenAPI.

Añadir en pom.xml:

1<dependency>
2    <groupId>org.springdoc</groupId>
3    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
4    <version>2.5.0</version>
5</dependency>

3. Ejecutar la aplicación #

Arrancamos Spring Boot normalmente.

Luego abrimos en el navegador:

1http://localhost:8080/swagger-ui.html

o

1http://localhost:8080/swagger-ui/index.html

Aparecerá la interfaz Swagger.

4. Qué veremos en Swagger #

Swagger muestra automáticamente:

• todos los controllers
• rutas
• métodos HTTP
• parámetros
• respuestas

Ejemplo:

1GET /users
2POST /users
3GET /users/{id}
4DELETE /users/{id}

También permite ejecutar las peticiones.

5. Ejemplo Controller #

1@RestController
2@RequestMapping("/users")
3public class UserController {
4
5    @GetMapping
6    public List<UserDTO> getUsers() {
7        return List.of(new UserDTO(1L,"Ana","ana@email.com"));
8    }
9
10}

Swagger generará automáticamente la documentación.

6. Probar endpoints desde Swagger #

Swagger incluye un botón:

1Try it out

Esto permite enviar peticiones HTTP directamente desde la interfaz.

Por ejemplo:

1GET /users

Swagger ejecuta la petición y muestra la respuesta.

7. Documentar endpoints con anotaciones #

Podemos añadir información adicional usando anotaciones.

8. Ejemplo #

1@Operation(summary = "Obtener lista de usuarios")
2@GetMapping("/users")
3public List<UserDTO> getUsers() {
4
5    return service.getUsers();
6
7}

9. Documentar parámetros #

1@Operation(summary = "Obtener usuario por id")
2@GetMapping("/users/{id}")
3public UserDTO getUser(
4        @Parameter(description="ID del usuario")
5        @PathVariable Long id) {
6
7    return service.getUser(id);
8
9}

10. Documentar request body #

Ejemplo:

1@Operation(summary="Crear usuario")
2@PostMapping("/users")
3public UserDTO createUser(
4        @RequestBody CreateUserDTO dto) {
5
6    return service.createUser(dto);
7
8}

Swagger mostrará automáticamente el JSON esperado.

11. Documentar respuestas #

También podemos documentar respuestas.

12. Ejemplo #

1@Operation(summary="Obtener usuario")
2@ApiResponses({
3        @ApiResponse(responseCode="200", description="Usuario encontrado"),
4        @ApiResponse(responseCode="404", description="Usuario no encontrado")
5})
6@GetMapping("/users/{id}")
7public UserDTO getUser(@PathVariable Long id) {
8
9    return service.getUser(id);
10
11}

13. Ejemplo JSON mostrado en Swagger #

Swagger genera ejemplos como este:

1{
2  "id": 1,
3  "name": "Ana",
4  "email": "ana@email.com"
5}

Esto ayuda a los desarrolladores a entender cómo usar la API.

14. Agrupar APIs #

Podemos agrupar endpoints.

15. Ejemplo #

1@Tag(name="Users", description="Operaciones sobre usuarios")
2@RestController
3@RequestMapping("/users")
4public class UserController {
5
6}

Swagger mostrará una sección llamada:

1Users

16. Cambiar información de la API #

Podemos definir información global.

17. Ejemplo #

1@Configuration
2public class OpenApiConfig {
3
4    @Bean
5    public OpenAPI apiInfo() {
6
7        return new OpenAPI()
8                .info(new Info()
9                        .title("API Usuarios")
10                        .description("API para gestionar usuarios")
11                        .version("1.0"));
12
13    }
14
15}

18. Ventajas de Swagger #

19. Swagger en producción #

En producción a veces se desactiva Swagger por seguridad.

Ejemplo:

1springdoc.api-docs.enabled=false