Generación Swagger/OpenAPI para Java: mejores bibliotecas

Generación Swagger/OpenAPI para Java: guía completa de herramientas

En el desarrollo moderno de Java, la creación de documentación de API de calidad se ha convertido en una parte integral del proceso. La especificación OpenAPI (anteriormente conocida como Swagger) proporciona un formato estandarizado para describir APIs RESTful. En este artículo, revisaremos las principales herramientas para generar documentación Swagger/OpenAPI en proyectos Java, sus características y ejemplos de uso.

¿Qué son Swagger y OpenAPI?

Swagger es un conjunto de herramientas para diseñar, crear y documentar APIs REST. OpenAPI es una especificación que define el estándar de descripción de APIs. Swagger es la implementación más popular de esta especificación.

Bibliotecas principales para Java

Consideremos tres herramientas clave:

• SpringDoc OpenAPI — una biblioteca moderna para Spring Boot
• Swagger Core — la biblioteca base de los creadores de Swagger
• OpenAPI Generator — una herramienta para generar código y documentación

1. SpringDoc OpenAPI

SpringDoc es la opción más popular para proyectos en Spring Boot. Se integra automáticamente con su aplicación y genera documentación basada en anotaciones y tipos de datos.

Instalación y configuración

Agregue la dependencia en pom.xml:

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

Ejemplo de uso

Cree un controlador simple con documentación:

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

    @GetMapping("/{id}")    @Operation(summary = "Obtener usuario por ID")    public ResponseEntity<User> getUser(            @Parameter(description = "ID del usuario")            @PathVariable Long id) {        // implementación        return ResponseEntity.ok(new User(id, "Iván"));    }

    @PostMapping    @Operation(summary = "Crear un nuevo usuario")    public ResponseEntity<User> createUser(            @RequestBody @Valid CreateUserRequest request) {        // implementación        return ResponseEntity.status(201).body(new User(1L, request.getName()));    }}

Después de iniciar la aplicación, la documentación estará disponible en http://localhost:8080/swagger-ui.html.

2. Swagger Core

La biblioteca Swagger Core proporciona un enfoque de más bajo nivel para crear la especificación OpenAPI. Es adecuada para proyectos donde se requiere un control total sobre la generación.

Ejemplo de creación manual de especificación

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

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("Pet Store API")        .description("API para gestionar mascotas")        .version("1.0.0")        .contact(new Contact()            .name("Desarrollador")            .email("dev@example.com")))    .addServersItem(new Server()        .url("https://api.example.com/v1")        .description("Servidor de producción"));

// Agregar rutas y componentesPaths paths = new Paths();paths.addPathItem("/pets", new PathItem()    .get(new Operation()        .operationId("listPets")        .summary("Obtener lista de mascotas")));openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator es una herramienta que puede generar tanto documentación como código de cliente/servidor basado en la especificación OpenAPI.

Uso en Maven

Agregue el plugin en pom.