OpenAPI / Swagger Java: métodos, ejemplos, instalación |…

¿Qué es OpenAPI / Swagger y por qué lo necesita un desarrollador Java?

\n\n

OpenAPI (anteriormente conocido como Swagger) es una especificación para describir, crear, documentar y consumir APIs RESTful. Para el desarrollador Java, las bibliotecas OpenAPI / Swagger son una herramienta indispensable que automatiza el proceso de documentación de APIs y generación de código cliente.

\n\n

Razones principales para usar OpenAPI / Swagger en proyectos Java:

Generación automática de documentación — la biblioteca analiza su código (anotaciones de Spring Boot, JAX-RS) y crea documentación interactiva en formato Swagger UI.
Estandarización — formato único de descripción de API, comprensible tanto para personas como para máquinas.
Generación de código cliente — se puede generar un cliente Java para cualquier API descrita en OpenAPI.
Pruebas — Swagger UI permite realizar solicitudes a la API directamente desde el navegador.
Integración con CI/CD — se puede verificar la conformidad de la API con la especificación en la etapa de compilación.

\n\n

En este artículo, veremos las dos bibliotecas Java principales: springdoc-openapi (para Spring Boot) y Swagger Core (para JAX-RS y otros frameworks).

\n\n

Instalación de la biblioteca OpenAPI / Swagger para Java

\n\n

La instalación depende del framework utilizado. Consideremos las dos opciones principales.

\n\n

Opción 1: Spring Boot (springdoc-openapi)

Agregue la dependencia a su pom.xml (Maven):

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

\n\n

Para Gradle (build.gradle):

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

\n\n

Opción 2: JAX-RS / Jakarta (Swagger Core)

Maven:

<dependency>\n    <groupId>io.swagger.core.v3</groupId>\n    <artifactId>swagger-jaxrs2-jakarta</artifactId>\n    <version>2.2.22</version>\n</dependency>

\n\n

Gradle:

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

\n\n

Inicio rápido: primer ejemplo con Spring Boot

\n\n

Después de agregar la dependencia springdoc-openapi en un proyecto Spring Boot, Swagger UI está disponible automáticamente en la dirección http://localhost:8080/swagger-ui.html. Creemos un controlador simple:

\n\n

import io.swagger.v3.oas.annotations.Operation;\nimport io.swagger.v3.oas.annotations.tags.Tag;\nimport org.springframework.web.bind.annotation.*;\n\n@RestController\n@RequestMapping("/api/users")\n@Tag(name = "User Controller", description = "Gestión de usuarios")\npublic class UserController {\n\n    @GetMapping("/{id}")\n    @Operation(summary = "Obtener usuario por ID")\n    public String getUser(@PathVariable Long id) {\n        return "User with ID: " + id;\n    }\n\n    @PostMapping\n    @Operation(summary = "Crear nuevo usuario")\n    public String createUser(@RequestBody String userName) {\n        return "Created user: " + userName;\n    }\n}

\n\n

Después de iniciar la aplicación, abra http://localhost:8080/swagger-ui.html — verá documentación interactiva con la posibilidad de realizar solicitudes.

\n\n