Tutorial SpringBoot: Open API y cómo agregarlo en Spring Boot

Qué es Open API y cómo se agregar en Spring Boot 3

OpenAPI es una especificación estándar para describir interfaces de programación de aplicaciones (API) RESTful. Su principal objetivo es facilitar la comunicación entre diferentes sistemas mediante una descripción clara y estructurada de los endpoints, métodos, parámetros y respuestas que una API ofrece. Al adoptar OpenAPI, los desarrolladores pueden generar documentación interactiva, realizar pruebas automatizadas y asegurar la consistencia entre los distintos entornos de desarrollo.

Integrar OpenAPI en una aplicación Spring Boot 3 implica varios pasos que optimizan la gestión y el mantenimiento de las API. Para comenzar, es necesario añadir las dependencias pertinentes en el archivo build.gradle o pom.xml. Por ejemplo, utilizando Maven, se incluiría la dependencia de springdoc-openapi-ui:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>2.3.0</version>
</dependency>

Una vez configuradas las dependencias, Spring Boot detecta automáticamente las clases controladoras y genera la documentación correspondiente basada en las anotaciones existentes.

Adicionalmente, Spring Boot 3 permite acceder a la interfaz de usuario de OpenAPI mediante una URL específica, generalmente http://localhost:8080/swagger-ui.html o http://localhost:8080/swagger-ui/index.html.

Esta interfaz proporciona una representación visual interactiva de la API, facilitando la exploración y prueba de los endpoints directamente desde el navegador.

Ejemplo:

Diferencias entre Open API y Swagger

OpenAPI y Swagger son términos que a menudo se utilizan de manera intercambiable, pero representan conceptos distintos dentro del ecosistema de desarrollo de APIs.

Mientras que OpenAPI se refiere a una especificación estándar para describir APIs RESTful, Swagger es un conjunto de herramientas que implementan esta especificación.

La especificación OpenAPI define un formato estructurado para describir las funcionalidades de una API, incluyendo sus endpoints, métodos HTTP, parámetros, respuestas y esquemas de datos. Esta especificación facilita la comunicación y la colaboración entre desarrolladores, permitiendo una comprensión clara y unificada de cómo funciona una API.

Al adoptar OpenAPI, los equipos pueden generar automáticamente documentación, realizar pruebas y asegurar la consistencia entre diferentes entornos y versiones de la API.

Por otro lado, Swagger es el ecosistema de herramientas que facilita la implementación y el uso de la especificación OpenAPI. Incluye componentes como Swagger Editor, Swagger UI y Swagger Codegen. Swagger UI, por ejemplo, proporciona una interfaz gráfica interactiva que permite a los desarrolladores explorar y probar los endpoints de una API directamente desde el navegador. Esta interfaz se integra fácilmente con aplicaciones Spring Boot 3, permitiendo una visualización dinámica de la documentación generada a partir de las definiciones OpenAPI.

Una diferencia clave radica en que OpenAPI es una especificación pública mantenida por la OpenAPI Initiative, mientras que Swagger originalmente fue desarrollado por la empresa Swagger, que más tarde fue adquirida por SmartBear. Aunque Swagger sigue siendo una parte integral del ecosistema de OpenAPI, su rol principal es proporcionar las herramientas necesarias para trabajar con la especificación.

Además, en versiones recientes, Swagger ha ampliado su funcionalidad para incluir características avanzadas como la generación de código cliente y servidor a partir de las definiciones OpenAPI. Esto permite a los desarrolladores acelerar el proceso de creación de aplicaciones al generar automáticamente los esqueletos de código basados en la especificación de la API.

Anotaciones de Open API para usar en controladores y DTOs

El uso de anotaciones de OpenAPI en controladores y DTOs (Data Transfer Objects) es fundamental para enriquecer la documentación de las APIs y garantizar una claridad en la comunicación de los contratos entre el servidor y los clientes. Estas anotaciones permiten especificar detalles precisos sobre los endpoints, los parámetros esperados y las estructuras de datos utilizadas, lo que facilita tanto el desarrollo como el consumo de la API.

En los controladores, se emplean principalmente anotaciones como @Operation, @ApiResponse y @Parameter. La anotación @Operation se utiliza para describir la operación que realiza un endpoint específico, proporcionando un resumen y una descripción detallada de su funcionalidad. Por ejemplo:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/productos")
public class ProductoController {

    @Operation(
        summary = "Obtener lista de productos",
        description = "Retorna una lista paginada de todos los productos disponibles en el sistema."
    )
    @ApiResponse(responseCode = "200", description = "Lista de productos obtenida exitosamente")
    @GetMapping
    public List<Producto> obtenerProductos(
            @Parameter(description = "Página que se desea obtener", example = "0") 
            @RequestParam(defaultValue = "0") int pagina,
            @Parameter(description = "Número de elementos por página", example = "10") 
            @RequestParam(defaultValue = "10") int tamaño) {
        // Lógica para obtener productos
    }
}

En este ejemplo, @Operation proporciona un resumen y una descripción de la operación, mientras que @ApiResponse especifica la respuesta esperada. Las anotaciones @Parameter detallan cada uno de los parámetros de la petición, mejorando la comprensión de cómo interactuar con el endpoint.

Por otro lado, en los DTOs, se utilizan anotaciones como @Schema para definir la estructura y las restricciones de los datos que se intercambian. Esto asegura que la documentación refleje con precisión los modelos de datos utilizados. Por ejemplo:

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

public class ProductoDTO {

    @Schema(description = "Identificador único del producto", example = "12345", required = true)
    private Long id;

    @Schema(description = "Nombre del producto", example = "Smartphone XYZ", maxLength = 100, required = true)
    private String nombre;

    @Schema(description = "Descripción detallada del producto", example = "Smartphone con 128GB de almacenamiento", maxLength = 500)
    private String descripcion;

    @Schema(description = "Precio del producto", example = "499.99", minimum = "0", required = true)
    private BigDecimal precio;

    // Getters y setters
}

En este caso, @Schema define cada campo del DTO, especificando descripciones, ejemplos y restricciones como maxLength o minimum. Esto no solo mejora la generación de la documentación, sino que también facilita la validación de los datos en tiempo de ejecución.

Además de estas anotaciones básicas, existen otras como @ApiResponse, que permite definir múltiples respuestas posibles para un mismo endpoint, y @RequestBody, que describe el cuerpo de la solicitud en operaciones que lo requieran. La combinación adecuada de estas anotaciones en controladores y DTOs resulta en una documentación precisa y detallada, que refleja fielmente el comportamiento y las expectativas de la API.

Es importante destacar que, al utilizar estas anotaciones, se favorece la mantenibilidad del código y la coherencia en la documentación, ya que cualquier cambio en los controladores o en los modelos de datos se refleja automáticamente en la especificación OpenAPI generada. Asimismo, herramientas como Swagger UI se benefician de esta riqueza de información para proporcionar interfaces interactivas que facilitan la exploración y prueba de los endpoints.

Finalmente, es recomendable seguir las mejores prácticas al aplicar estas anotaciones, asegurando que cada endpoint y cada DTO estén debidamente documentados y que las descripciones sean claras y concisas. De esta manera, se potencia la calidad de la API y se facilita tanto su uso por parte de desarrolladores como su mantenimiento a lo largo del ciclo de vida del proyecto.

Configuración del @Bean de Open API

Para personalizar la configuración de OpenAPI en una aplicación Spring Boot 3, es esencial definir un bean específico que permita ajustar diversos aspectos de la documentación generada automáticamente. Este enfoque proporciona un control detallado sobre la información presentada, mejorando la claridad y usabilidad de la API para los consumidores.

En primer lugar, es necesario crear una clase de configuración marcada con la anotación @Configuration. Dentro de esta clase, se declara el método que devuelve una instancia de OpenAPI. Este método está anotado con @Bean, lo que indica a Spring que debe gestionar este objeto como un componente del contexto de la aplicación.

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API de Gestión de Productos")
                        .version("2.0")
                        .description("Esta API permite gestionar productos en el inventario.")
                        .contact(new Contact()
                                .name("Soporte Técnico")
                                .email("soporte@ejemplo.com")))
                .components(new Components()
                        .addSecuritySchemes("BearerAuth",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

En el ejemplo anterior, la configuración del bean de OpenAPI incluye la personalización de la información básica de la API mediante el objeto Info. Aquí se especifica el título, la versión, una descripción detallada y los datos de contacto del responsable de la API. Esta información es fundamental para que los usuarios comprendan el propósito y el respaldo de la API.

Además, se configuran los componentes de seguridad utilizando la clase Components. En este caso, se añade un esquema de seguridad de tipo HTTP Bearer con formato JWT. Esta configuración es esencial para definir cómo se autenticarán las solicitudes a la API, proporcionando una capa adicional de seguridad y asegurando que solo los usuarios autorizados puedan acceder a los recursos.

Es posible extender esta configuración para incluir otros aspectos, como Servers, que definen los entornos donde está desplegada la API, o Tags, que permiten agrupar los endpoints de manera lógica. A continuación, se presenta un ejemplo de cómo añadir estos elementos adicionales:

@Bean
public OpenAPI extendedOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("API de Gestión de Productos")
                    .version("2.0")
                    .description("Esta API permite gestionar productos en el inventario.")
                    .contact(new Contact()
                            .name("Soporte Técnico")
                            .email("soporte@ejemplo.com")))
            .servers(List.of(
                    new Server().url("https://api.ejemplo.com/v2").description("Servidor de Producción"),
                    new Server().url("https://staging.api.ejemplo.com").description("Servidor de Staging")))
            .components(new Components()
                    .addSecuritySchemes("BearerAuth",
                            new SecurityScheme()
                                    .type(SecurityScheme.Type.HTTP)
                                    .scheme("bearer")
                                    .bearerFormat("JWT")))
            .addTagsItem(new Tag().name("Productos").description("Operaciones relacionadas con productos"))
            .addTagsItem(new Tag().name("Usuarios").description("Operaciones relacionadas con usuarios"));
}

En este segundo ejemplo, se añaden dos servidores diferentes, uno para el entorno de Producción y otro para Staging, facilitando la gestión de distintos entornos de despliegue. Además, se incluyen dos tags: uno para las operaciones relacionadas con Productos y otro para Usuarios, lo que organiza de manera más coherente los endpoints en la documentación generada.

Es importante también considerar la integración de global responses y external documentation para enriquecer aún más la especificación de la API. Por ejemplo:

@Bean
public OpenAPI comprehensiveOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("API de Gestión de Productos")
                    .version("2.0")
                    .description("Esta API permite gestionar productos en el inventario.")
                    .contact(new Contact()
                            .name("Soporte Técnico")
                            .email("soporte@ejemplo.com")))
            .components(new Components()
                    .addSecuritySchemes("BearerAuth",
                            new SecurityScheme()
                                    .type(SecurityScheme.Type.HTTP)
                                    .scheme("bearer")
                                    .bearerFormat("JWT"))
                    .addResponses("NotFound", new ApiResponse().description("Recurso no encontrado"))
                    .addResponses("Unauthorized", new ApiResponse().description("No autorizado")))
            .externalDocs(new ExternalDocumentation()
                    .description("Documentación Adicional")
                    .url("https://docs.ejemplo.com"))
            .addSecurityItem(new SecurityRequirement().addList("BearerAuth"))
            .addTagsItem(new Tag().name("Productos").description("Operaciones relacionadas con productos"));
}

En este fragmento de código, se definen respuestas globales como NotFound y Unauthorized, que pueden ser referenciadas en múltiples endpoints, reduciendo la redundancia en las descripciones de las respuestas de error. Además, se integra una documentación externa que proporciona recursos adicionales para los desarrolladores que deseen profundizar en ciertos aspectos de la API.

La correcta configuración del @Bean de OpenAPI no solo mejora la calidad de la documentación generada, sino que también facilita el mantenimiento y la evolución de la API a lo largo del tiempo. Al centralizar la configuración en un único punto, se asegura la coherencia en toda la especificación y se simplifica la incorporación de nuevas características o ajustes necesarios.

Es recomendable revisar periódicamente la configuración del bean de OpenAPI para adaptarla a los cambios en los requerimientos de la API y asegurar que la documentación permanezca actualizada y precisa. De esta manera, se garantiza que los consumidores de la API tengan acceso a información fiable y útil, optimizando la experiencia de desarrollo y reduciendo posibles malentendidos o errores en la integración.