giuseppe-trisciuoglio/spring-boot-openapi-documentation

¿Qué hace spring-boot-openapi-documentation?

Proporciona patrones para generar documentación completa de API REST utilizando SpringDoc OpenAPI 3.0 y Swagger UI en aplicaciones Spring Boot 3.x. Útil al configurar documentación de API, configurar Swagger UI, agregar anotaciones OpenAPI, implementar documentación de seguridad o mejorar endpoints REST con ejemplos y esquemas.

Dependencia de Maven

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

Dependencia de Gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

Configuración de Spring Boot

Después de agregar la dependencia, SpringDoc OpenAPI y Swagger UI se configurarán automáticamente. La UI de Swagger estará disponible en:

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

El documento OpenAPI estará disponible en:

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

Personalización de la Documentación de la API

Para personalizar la información de la API, agrega las siguientes propiedades a tu archivo application.yml o application.properties:

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha
    try-it-out-enabled: true
    filter: true
    display-request-duration: true

springdoc:
  info:
    title: API de Mi Aplicación
    description: Documentación de API para Mi Aplicación
    version: v1.0.0
    contact:
      name: Soporte de API
      email: [email protected]
      url: https://ejemplo.com/soporte
    license:
      name: Apache 2.0
      url: https://www.apache.org/licenses/LICENSE-2.0.html

O en application.properties:

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha
springdoc.swagger-ui.try-it-out-enabled=true
springdoc.swagger-ui.filter=true
springdoc.swagger-ui.display-request-duration=true

# Información personalizada de la API
springdoc.info.title=API de Mi Aplicación
springdoc.info.description=Documentación de API para Mi Aplicación
springdoc.info.version=v1.0.0
springdoc.info.contact.name=Soporte de API
[email protected]
springdoc.info.contact.url=https://ejemplo.com/soporte
springdoc.info.license.name=Apache 2.0
springdoc.info.license.url=https://www.apache.org/licenses/LICENSE-2.0.html

Anotaciones OpenAPI para Controladores REST

Uso básico

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;

@RestController
@RequestMapping("/api/usuarios")
@Tag(name = "Gestión de Usuarios", description = "Operaciones de gestión de usuarios")
public class UsuarioController {

    @GetMapping("/{id}")
    @Operation(summary = "Obtener usuario por ID", description = "Devuelve un solo usuario por su ID")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Usuario encontrado exitosamente",
                     content = @Content(mediaType = "application/json",
                     schema = @Schema(implementation = Usuario.class))),
        @ApiResponse(responseCode = "404", description = "Usuario no encontrado",
                     content = @Content)
    })
    public ResponseEntity<Usuario> obtenerUsuario(@PathVariable Long id) {
        // implementación
    }
}

Anotaciones a nivel de modelo

import io.swagger.v3.oas.annotations.media.Schema;

@Data
@Schema(description = "Entidad que representa un usuario en el sistema")
public class Usuario {

    @Schema(description = "Identificador único del usuario", example = "1", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(description = "Nombre del usuario", example = "Juan Pérez", requiredMode = Schema.RequiredMode.REQUIRED)
    private String nombre;

    @Schema(description = "Dirección de correo electrónico del usuario", example = "[email protected]", requiredMode = Schema.RequiredMode.REQUIRED)
    private String email;

    @Schema(description = "Edad del usuario", example = "30", minimum = "0", maximum = "150")
    private Integer edad;
}

Documentación de Seguridad

Configuración de JWT Bearer Token

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;

@Configuration
@OpenAPIDefinition(
    info = @Info(title = "API de Mi Aplicación", version = "v1.0.0"),
    security = @SecurityRequirement(name = "bearerAuth")
)
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class OpenApiConfig {
}

Configuración de Autenticación Básica

@Configuration
@SecurityScheme(
    name = "basicAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "basic"
)
public class OpenApiBasicAuthConfig {
}

Configuración Avanzada

Agrupación de APIs por paquetes

springdoc:
  packages-to-scan: com.ejemplo.api.controladores, com.ejemplo.api.dto
  paths-to-match: /api/**

Desactivar Swagger UI en ciertos perfiles

# En application-prod.yml
springdoc:
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

Agrupación de APIs

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGroupConfig {

    @Bean
    public GroupedOpenApi apiPublica() {
        return GroupedOpenApi.builder()
            .group("pública")
            .pathsToMatch("/api/public/**")
            .build();
    }

    @Bean
    public GroupedOpenApi apiAdmin() {
        return GroupedOpenApi.builder()
            .group("admin")
            .pathsToMatch("/api/admin/**")
            .build();
    }
}

Verificación

1. Inicia tu aplicación Spring Boot
2. Abre un navegador y navega a http://localhost:8080/swagger-ui.html
3. Explora los endpoints documentados
4. Opcionalmente, usa la función "Probar ahora" para probar los endpoints directamente desde la UI de Swagger