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

Introducción a OpenAPI en Spring Boot

OpenAPI, anteriormente conocido como Swagger, es una especificación para la descripción de APIs REST de manera estándar y comprensible tanto para humanos como para máquinas. La integración de OpenAPI en un proyecto Spring Boot facilita la documentación y prueba de APIs, mejorando la colaboración y la calidad del desarrollo.

Crear un Proyecto Spring Boot con Spring Web

Para comenzar, crea un nuevo proyecto Spring Boot seleccionando Spring Web como dependencia. Este será tu punto de partida para desarrollar servicios REST y documentarlos con OpenAPI.

Añadir OpenAPI al Proyecto

Para integrar OpenAPI en tu proyecto, añade la siguiente dependencia al pom.xml. Esta dependencia habilita la documentación automática de la API utilizando OpenAPI 3.

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

Visita springdoc.org para más información sobre la dependencia y sus configuraciones.

Crear un Controlador en Spring Boot

Desarrolla un controlador que exponga endpoints REST. Por ejemplo, un controlador simple que devuelve un String y otro que devuelve un objeto de una clase personalizada podría lucir así:

@RestController
public class MiControlador {

    @GetMapping("/texto")
    public String getTexto() {
        return "Ejemplo de texto";
    }

    @GetMapping("/objeto")
    public MiObjeto getObjeto() {
        return new MiObjeto("Ejemplo", 123);
    }

    static class MiObjeto {
        private String nombre;
        private int valor;

        // Constructor, getters y setters
    }
}

Arrancar el Proyecto y Visualizar la Documentación de la API

Una vez que tu proyecto esté corriendo, puedes acceder a la UI de Swagger para visualizar la documentación de tu API navegando a:

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

En esta interfaz, verás listados todos tus endpoints, modelos de datos, y podrás incluso probar las llamadas a la API directamente desde el navegador.

Diferencia entre Swagger y OpenAPI

Swagger: Se refiere al conjunto de herramientas de código abierto que se utilizan para diseñar, construir, documentar y utilizar APIs RESTful. Incluye la especificación Swagger (ahora OpenAPI), la UI de Swagger para visualizar la documentación de la API, Swagger Codegen para generar código de cliente y servidor, entre otras herramientas.

OpenAPI: Es la especificación utilizada para describir APIs RESTful. Originalmente parte de Swagger, la especificación fue donada a la Linux Foundation y renombrada como OpenAPI Specification (OAS). Define un estándar y un lenguaje neutral para describir la estructura de las APIs REST, facilitando su comprensión y utilización.

Esta lección te proporciona las bases para comenzar a trabajar con OpenAPI en proyectos Spring Boot, desde la configuración inicial hasta la documentación y prueba de tus APIs REST, aprovechando las herramientas y estándares actuales en el desarrollo de interfaces de programación de aplicaciones.