Spring Boot 3 + Spring Doc + Swagger : Un ejemplo

La documentación de las APIs debe ser una prioridad para el equipo de desarrollo, sobre todo porque permite clarificar el contrato para que otros desarrolladores y los analistas de calidad (QA) puedan comunicarse y testear nuestros servicios respectivamente.

La forma más extendida actualmente de documentar nuestras APIs es haciendo uso del estándar Open API, cuya implementación más conocida es Swagger. Swagger por su parte se divide en dos componentes fundamentales: Swagger Doc y Swagger UI.

• Swagger Doc es la documentación de la API en si, pero en formato no entendible para los humanos, por ejemplo un archivo JSON o YML que contiene la especificación de la documentación.
• Swagger UI es una interfaz gráfica (UI) que se visualiza normalmente junto a los proyectos y que “renderiza” la especificación creada en Swagger Doc.

Este artículo está explicado en un video en nuestro canal de Youtube, si deseas puedes darle una mirada acá:

Adicionalmente a Swagger se ha creado una capa de nivel superior, construida para proyectos Spring Boot llamada SpringDoc, la cual simplifica aun mas el proceso de documentación de nuestras API, reduciéndolo a incluir una simple dependencia y nace la magia.

Arquitectura de Springdoc

Para hacer funcionar esta librería con nuestro proyecto Spring Boot 3 agregaremos las siguientes dependencias:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>3.0.2</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.sacavix.boot3</groupId>
	<artifactId>swagger-with-springboot3</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>swagger-with-springboot3</name>
	<description>Demo project for Spring Boot</description>
	<properties>
		<java.version>17</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>

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

	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>

	</build>

</project>
Footer

Al agregar la dependencia springdoc-openapi-starter-webmvc-ui, estamos asumiendo que el proyecto será un Spring MVC tradicional (servlet app), si se va a usar el stack reactivo como webflux cambia la dependencia, consulte la documentación para ello.

Con lo anterior ya es suficiente para que aparezca la API documentada, sin embargo, podemos configurar algunas cuestiones adicionales del Swagger UI, para ello agreguemos un Bean a nuestra aplicación con la siguiente estructura:

@Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("SACAViX Spring Boot 3 API -------")
                        .version("0.11")
                        .description("Sample app Spring Boot 3 with Swagger")
                        .termsOfService("http://swagger.io/terms/")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")));

    }

Puede adicionalmente consultar el código fuente de este ejemplo completo, el mismo esta disponible en nuestro repositorio de GitHub .

Espero te sea util el artículo, te invito a que nos sigas en Youtube