Swagger (OpenAPI)

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

@Tag(name = "Autenticación", description = "API de autenticación y autorización")
@RestController
@RequestMapping("/v1/auth")
public class AuthController {
    // ...
}

/**
 * Endpoint para renovar el token de acceso.
 * Utiliza el token de actualización para generar un nuevo token de acceso.
 *
 * @param request DTO que contiene el token de actualización
 * @return ResponseEntity con AuthResponse que incluye los nuevos tokens
 */
@Operation(summary = "Renovar token", 
          description = "Genera un nuevo token de acceso usando el token de actualización")
@ApiResponses(value = {
    @ApiResponse(
        responseCode = "200", 
        description = "Token renovado exitosamente"
    ),
    @ApiResponse(
        responseCode = "400", 
        description = "Token de actualización inválido o malformado",
        content = @Content(
            mediaType = MediaType.APPLICATION_JSON_VALUE, 
            schema = @Schema(implementation = ErrorResponse.class)
        )
    )
    // ... más respuestas
})
@PostMapping("/refresh-token")

@Tag(name = "Usuarios", description = "Operaciones relacionadas con usuarios")

@Operation(
    summary = "Crear usuario", 
    description = "Crea un nuevo usuario en el sistema"
)

@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "Usuario creado"),
    @ApiResponse(responseCode = "400", description = "Datos inválidos")
})

@Parameter(
    name = "id", 
    description = "ID del usuario", 
    required = true, 
    example = "123"
)

@Schema(description = "Respuesta de autenticación")
public class AuthResponse {
    @Schema(description = "Token de acceso JWT", 
           example = "eyJhbGciOiJ...")
    private String accessToken;
}

@Configuration
@SecurityScheme(
    name = "Bearer Authentication",    // Nombre del esquema de seguridad
    type = SecuritySchemeType.HTTP,    // Tipo HTTP para autenticación
    bearerFormat = "JWT",             // Formato del token (JWT)
    scheme = "bearer"                  // Esquema bearer
)
public class SwaggerConfig {
    
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("JWT Spring Boot API")           // Título de la API
                        .description("API de autenticación y autorización con JWT")
                        .version("v1")                         // Versión de la API
                        .license(new License()                 // Información de licencia
                                .name("Programando en Java")
                                .url("https://programandoenjava.com")))
                .externalDocs(new ExternalDocumentation()      // Documentación externa
                        .description("Documentación completa")
                        .url("https://jwt-spring-boot.programandoenjava.com/docs"));
    }
}

@SecurityRequirement(name = "Bearer Authentication")
@Operation(summary = "Endpoint protegido")
@GetMapping("/protected")
public ResponseEntity<String> protectedEndpoint() {
    // ... código del endpoint
}

// A nivel de clase - aplica a todos los endpoints del controlador
@SecurityRequirement(name = "Bearer Authentication")
@RestController
@RequestMapping("/v1/users")
public class UserController {
    // todos los endpoints requerirán autenticación
}
 
// A nivel de método - aplica solo a endpoints específicos
@RestController
@RequestMapping("/v1/products")
public class ProductController {
    
    @SecurityRequirement(name = "Bearer Authentication")
    @GetMapping("/private")
    public ResponseEntity<String> privateEndpoint() {
        // endpoint protegido
    }
 
    @GetMapping("/public")
    public ResponseEntity<String> publicEndpoint() {
        // endpoint público
    }
}