Documentación de API con Spring Boot y OpenAPI

Este tutorial explica cómo documentar APIs en una aplicación Spring Boot usando springdoc-openapi, cómo personalizar la documentación, cómo generar el JSON (OpenAPI) y cómo importarlo en Postman.

Contrato breve

• Entrada: proyecto Spring Boot con controladores REST.
• Salida: documentación OpenAPI disponible en /v3/api-docs (JSON) y pasos para importar en Postman.
• Modos de error: endpoints privados o protegidos requieren autenticación para obtener el JSON.

---

1) Dependencias

Maven (pom.xml):

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

Nota: Ajusta la versión a la más reciente estable en el momento de uso.

---

2) Comportamiento por defecto

Al añadir la dependencia, springdoc expone automáticamente:

• JSON OpenAPI: http://localhost:8080/v3/api-docs
• YAML OpenAPI: http://localhost:8080/v3/api-docs.yaml
• Swagger UI: http://localhost:8080/swagger-ui/index.html

---

3) Configuración y personalización

Ejemplo de bean OpenAPI (Java) para personalizar la metadata:

import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Mi API")
                .version("v1.0.0")
                .description("Documentación de ejemplo para Mi API"));
    }
}

También puedes usar @OpenAPIDefinition con @Info, @Servers, @Contact para anotar la clase principal.

---

4) Documentar controladores y operaciones

Usa las anotaciones de io.swagger.v3.oas.annotations:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/pets")
public class PetController {

    @Operation(summary = "Listar mascotas", description = "Devuelve todas las mascotas")
    @ApiResponse(responseCode = "200", description = "OK")
    @GetMapping
    public List<Pet> list() {
        return List.of();
    }
}

Las anotaciones permiten documentar parámetros, request bodies, respuestas y ejemplos.

---

5) Obtener y guardar el JSON OpenAPI

Arranca la aplicación y visita /v3/api-docs.

Para descargar con PowerShell (Windows / pwsh):

Invoke-WebRequest -Uri "http://localhost:8080/v3/api-docs" -OutFile openapi.json

# o
curl.exe "http://localhost:8080/v3/api-docs" -o openapi.json

---