Spring Boot 3 + OpenAPI (Swagger UI): guía paso a paso para documentar tu API REST

Si trabajas con Spring Boot 3 y necesitas documentar tu API REST sin depender de documentación manual, hoy la forma más práctica es usar OpenAPI con springdoc y exponer la documentación interactiva con Swagger UI. Esta combinación te permite generar documentación desde el código, probar endpoints desde el navegador y mantener alineadas la implementación real y la definición técnica de la API.

En esta guía paso a paso veremos cómo integrar OpenAPI en un proyecto Spring Boot 3, qué dependencia usar, cómo habilitar Swagger UI, cómo documentar controladores y respuestas, y qué errores conviene evitar cuando también usas seguridad, perfiles o rutas personalizadas.

Qué cambió: Swagger, OpenAPI y Spring Boot 3

Aunque muchas búsquedas siguen usando el término “Swagger”, en proyectos modernos con Spring Boot 3 lo más habitual es trabajar con la especificación OpenAPI y usar springdoc-openapi para generar la documentación. Swagger UI sigue siendo la capa visual para explorar y probar endpoints, pero la base de la documentación hoy es OpenAPI.

La ventaja de este enfoque es clara: reduces fricción entre desarrollo, QA e integraciones, y evitas que la documentación quede desactualizada frente al código real.

Cuándo conviene usar Swagger UI en tu API

Swagger UI es especialmente útil cuando necesitas:

• documentar endpoints REST de forma consistente;
• probar requests y responses desde el navegador;
• acelerar validaciones entre backend, frontend y QA;
• entregar una referencia clara para equipos internos o terceros.

En otras palabras, no se trata solo de “mostrar endpoints”, sino de darle más claridad operativa a la API antes de escalar su consumo.

Cómo integrar OpenAPI y Swagger UI en Spring Boot 3

Paso 1. Revisa tu versión actual y el enfoque de documentación

Antes de cambiar dependencias o anotaciones, revisa qué versión de Spring Boot estás usando y si tu proyecto todavía depende de bibliotecas antiguas como SpringFox. En Spring Boot 3, el enfoque recomendado suele pasar por springdoc-openapi.

Paso 2. Agrega la dependencia correcta en pom.xml

Para habilitar documentación OpenAPI con interfaz Swagger UI en un proyecto Maven, agrega una dependencia compatible con tu stack actual. Un ejemplo común es:

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

Si tu proyecto todavía usa una versión anterior del stack, valida en la documentación oficial de springdoc cuál es la variante correcta. Lo importante es que la dependencia quede alineada con Spring Boot 3 y con OpenAPI 3.

Paso 3. Elimina dependencias antiguas como SpringFox

Si tu proyecto todavía tiene esta dependencia:

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

conviene retirarla. En muchos proyectos, mantener SpringFox junto con springdoc genera conflictos, configuraciones duplicadas o resultados inconsistentes en la documentación.

Paso 4. Limpia configuraciones heredadas

Si tienes una clase como SwaggerConfig creada para una implementación anterior, revísala antes de mantenerla. En muchos casos, una parte importante de esa configuración ya no es necesaria o debe reescribirse para OpenAPI.

La recomendación aquí no es borrar por costumbre, sino simplificar el proyecto y evitar configuraciones que ya no aportan valor.

Paso 5. Declara la información general de la API

Puedes definir metadatos de la API desde la clase principal o desde una clase de configuración dedicada. Esto ayuda a mostrar nombre, versión, descripción, contacto y servidores dentro de la documentación generada.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.servers.Server;

@OpenAPIDefinition(
    info = @Info(
        title = "Nombre del microservicio",
        version = "1.0.0",
        description = "Documentación OpenAPI del microservicio",
        contact = @Contact(
            name = "Equipo responsable",
            email = "equipo@empresa.com"
        ),
        license = @License(
            name = "Apache 2.0"
        )
    ),
    servers = {
        @Server(description = "Local", url = "http://localhost:8080"),
        @Server(description = "QA", url = "https://qa.tu-dominio.com"),
        @Server(description = "Producción", url = "https://api.tu-dominio.com")
    }
)
@SpringBootApplication
public class NombreMicroservicioApplication {

    public static void main(String[] args) {
        SpringApplication.run(NombreMicroservicioApplication.class, args);
    }
}

Esta configuración mejora la legibilidad de la documentación y deja más contexto para quienes consumen la API.

Paso 6. Revisa propiedades de aplicación si necesitas personalizar rutas

En algunos casos conviene declarar propiedades específicas en application.yml o application.properties, por ejemplo para definir rutas, agrupar documentación o exponer el spec en una ubicación concreta.

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

Si no necesitas personalización, puedes empezar con la configuración por defecto y agregar estos ajustes más adelante.

Cómo documentar endpoints, parámetros y respuestas

La documentación se vuelve realmente útil cuando describe bien qué hace cada endpoint, qué parámetros espera y qué respuestas devuelve. Algunas de las anotaciones más utilizadas son:

• @Operation: resume el propósito del endpoint y agrega una descripción útil.
• @Parameter: documenta parámetros de entrada, especialmente path variables y query params.
• @ApiResponses: define los posibles códigos de respuesta y su significado.

Un ejemplo básico sería:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@Operation(
    summary = "Obtiene una solicitud por ID",
    description = "Retorna los datos asociados a la solicitud consultada",
    tags = { "solicitudes" }
)
@Parameter(
    name = "id",
    description = "Identificador único de la solicitud",
    required = true,
    example = "12345"
)
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Consulta generada correctamente"),
    @ApiResponse(responseCode = "204", description = "No se encontraron datos para el ID consultado"),
    @ApiResponse(responseCode = "500", description = "Error interno al procesar la consulta")
})

Aquí lo más importante es que la documentación refleje el comportamiento real del controller. Si una respuesta vacía en tu implementación equivale funcionalmente a 204, documentarla así puede evitar ambigüedades para el consumidor.

Cómo probar Swagger UI localmente

Una vez levantado el microservicio, puedes validar la documentación desde el navegador. Dependiendo de tu configuración, una ruta común es:

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

También conviene revisar el documento OpenAPI generado:

http://localhost:8080/v3/api-docs

Si ambos endpoints responden correctamente, ya tienes una buena base para revisar operaciones, schemas y responses antes de publicar el servicio en otros ambientes.

Errores comunes al integrar Swagger en Spring Boot

1. Swagger UI responde 404

Suele pasar por una dependencia incorrecta, una incompatibilidad de versiones o una ruta personalizada mal configurada.

2. La documentación no muestra todos los endpoints

Revisa si los controladores están dentro del escaneo de Spring, si existen filtros de seguridad que bloquean rutas o si algunas clases no están siendo detectadas correctamente.

3. Conflictos con Spring Security

Si usas seguridad, es habitual tener que permitir explícitamente el acceso a rutas como /swagger-ui/** y /v3/api-docs/**.

4. Configuración heredada de SpringFox

Si conviven bibliotecas o configuraciones antiguas con springdoc, la documentación puede comportarse de forma inconsistente.

Ventajas de documentar bien tu API desde el inicio

• Claridad técnica: reduce dudas sobre contratos, parámetros y respuestas.
• Mejor colaboración: backend, frontend y QA trabajan sobre la misma referencia.
• Menos fricción en integraciones: facilita consumo interno y externo de la API.
• Más velocidad operativa: probar endpoints desde Swagger UI acelera validaciones y debugging.

Conclusión

Integrar OpenAPI con Swagger UI en Spring Boot 3 no es solo una mejora para developers. También ordena la comunicación técnica, reduce errores entre equipos y mejora la calidad de las integraciones. Si la API va a crecer, la documentación no debería quedar para el final: conviene definirla con claridad desde la arquitectura.

¿Tu equipo necesita una base más clara para diseñar, documentar o escalar APIs?

En Kranio ayudamos a convertir decisiones técnicas complejas en soluciones más estructuradas y mantenibles. Si estás modernizando servicios, rediseñando contratos o buscando una documentación más útil para desarrollo y negocio, conversemos estratégicamente.