Generación Swagger/OpenAPI para Java: resumen de…

Generación Swagger/OpenAPI para Java: resumen completo de herramientas y bibliotecas

El desarrollo moderno de REST API en Java es impensable sin una documentación de calidad. El estándar OpenAPI (anteriormente conocido como Swagger Specification) se ha convertido en el estándar industrial de facto para describir HTTP API. En este artículo, analizaremos en detalle las principales bibliotecas y herramientas para generar especificaciones OpenAPI en aplicaciones Java, sus capacidades, ejemplos de uso y criterios de selección.

¿Qué es OpenAPI y para qué sirve?

OpenAPI es una especificación que describe una API RESTful en formato JSON o YAML. Incluye:

lista de endpoints y métodos HTTP;
modelos de datos (esquemas de solicitudes y respuestas);
parámetros (query, path, header);
información sobre autenticación y autorización.

La documentación generada con OpenAPI permite crear automáticamente SDK de cliente, realizar pruebas y mantener actualizada la descripción de la API. Para Java existen varias soluciones maduras.

1. SpringDoc OpenAPI (recomendado para Spring Boot)

SpringDoc es la biblioteca más popular para generar OpenAPI 3 en el ecosistema Spring. Escanea automáticamente los controladores, las anotaciones @RequestMapping, @GetMapping, etc., y construye la especificación basándose en ellas.

Configuración (Maven)

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

Ejemplo de controlador con anotaciones

@RestController@RequestMapping("/api/users")public class UserController {

    @Operation(summary = "Obtener usuario por ID")    @ApiResponses(value = {        @ApiResponse(responseCode = "200", description = "Usuario encontrado"),        @ApiResponse(responseCode = "404", description = "Usuario no encontrado")    })    @GetMapping("/{id}")    public ResponseEntity<User> getUser(@PathVariable Long id) {        // lógica        return ResponseEntity.ok(new User(id, "Iván", "ivan@example.com"));    }}

Después de iniciar la aplicación, la documentación está disponible en /swagger-ui.html y la especificación en JSON en /v3/api-docs.

2. Swagger Core (OpenAPI 3.0)

Swagger Core es una biblioteca de bajo nivel de los creadores de la especificación. Permite construir objetos OpenAPI de forma programática y serializarlos a JSON/YAML. Es adecuada para casos donde se necesita un control detallado de la generación.

Ejemplo de creación programática de una especificación

import io.swagger.v3.oas.models.*;import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("API de ejemplo")        .version("1.0.0")        .description("Documentación creada manualmente"))    .path("/hello", new PathItem()        .get(new Operation()            .summary("Saludo")            .operationId("sayHello")            .addParametersItem(new Parameter()                .name("name")                .in("query")                .required(false)                .schema(new StringSchema()))            .responses(new ApiResponses()                .addApiResponse("200", new ApiResponse()                    .description("OK")                    .content(new Content()                        .addMediaType("text/plain",                             new MediaType().schema(new StringSchema())))))));

// Serialización a JSONObjectMapper mapper = new ObjectMapper();String json = mapper.writeValueAsString(openAPI);System.out.println(json);