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

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

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

13.3 Ejecutar la aplicación

Arrancamos Spring Boot normalmente.

Luego abrimos en el navegador:

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

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

Aparecerá la interfaz Swagger.

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

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

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

13.7 Documentar endpoints con anotaciones

Podemos añadir información adicional usando anotaciones.

Ejemplo

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

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

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

13.10 Documentar respuestas

También podemos documentar respuestas.

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

13.12 Agrupar APIs

Podemos agrupar endpoints.

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

13.13 Cambiar información de la API

Podemos definir información global.

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}

13.14 Ventajas de Swagger

ventaja	explicación
documentación automática	no escribir docs manual
probar endpoints	desde navegador
mejor comunicación	frontend entiende la API
menos errores	contrato claro

13.15 Swagger en producción

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

Ejemplo:

1springdoc.api-docs.enabled=false

Curso de Spring Boot