En la actualidad, con la proliferación de las API REST ha cobrado importancia la automatización del proceso de documentarlas para:
- Ayudar a los consumidores del API a saber qué servicios se encuentran disponibles, su signatura, parámetros requeridos, etc.
- Proveer una forma simple y directa de probar los servicios y verificar si se encuentran disponibles.
- Los servicios siempre pueden estar sujetos a modificaciones, por lo que la automatización es importante para ayudar a mantener la documentación actualizada.
¿Qué es Swagger?
Swagger es un framework de código abierto que se utiliza para diseñar, documentar y probar un API RESTful. Permite a los desarrolladores crear documentación de API interactiva que describe los diversos endpoints, parámetros y respuestas de una API. Con Swagger, los desarrolladores pueden crear fácilmente una documentación clara y concisa para sus API, lo que reduce la necesidad de documentación manual y hace que las API sean más accesibles para otros desarrolladores. Además, Swagger proporciona una forma de probar las API directamente desde la documentación, lo que permite a los desarrolladores validar rápida y fácilmente la funcionalidad de sus API.
Swagger UI en particular nos permite documentar una REST API de forma automática además de proveer una interfaz web que nos permite interactuar con nuestra API.
En este artículo se demostrará como documentar un API REST con Swagger utilizando la implementación SpringFox de la especificación Swagger 2.
Proyecto para documentar un API REST con Swagger
Este artículo no cubre la creación del API REST sobre la cual generaremos la documentación vía Swagger. Puedes descargar el proyecto del siguiente artículo donde se explica cómo crear microservicios Spring Boot.

Agregar las dependencias de Maven
En el archivo pom.xml agregaremos las siguientes dependencias Maven:
- La implementación SpringFox (springfox-swagger2).
- La librería requerida para habilitar Swagger-UI (springfox-swagger-ui).
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Agregar la configuración mediante Docket
En este paso tenemos que:
- Crear una clase Java anotada con @Configuration y @EnableSwagger2.
- Implementar un método anotado con @Bean (en el ejemplo, el método api()) que retorne un objeto Docket. En este método se especifica la ruta a los controllers de nuestra API para que Swagger pueda localizarlos.
- Implementar un método que retorne un objeto ApiInfo (en el ejemplo, el método getApiInfo()), donde especificaremos atributos del API.
package com.jcodepoint.customerserviceswagger;
import java.util.Collections;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.jcodepoint.customerserviceswagger"))
.paths(PathSelectors.any())
.build()
.apiInfo(getApiInfo());
}
private ApiInfo getApiInfo() {
return new ApiInfo(
"Customer Service API",
"Customer Service API Documentation",
"1.0",
"https://jcodepoint.com/",
new Contact("jcodepoint", "https://jcodepoint.com", "jcodepoint@gmail.com"),
"LICENSE",
"LICENSE URL",
Collections.emptyList()
);
}
}
Acceder a la documentación del API
Podemos verificar la generación de los datos de nuestra API accediendo a la siguiente URL:
- http://localhost:8080/v2/api-docs
Como se puede observar, los datos son mostrados en formato JSon:

Para acceder a una interfaz más intuitiva podemos acceder a Swagger-UI con la siguiente URL:
- http://localhost:8080/swagger-ui.html

Conclusión
Como hemos visto en este artículo, Swagger es una herramienta poderosa para generar documentación de API que puede ayudar a los desarrolladores a comprender cómo interactuar con una API REST. Al integrar Swagger con una aplicación Spring Boot, los desarrolladores pueden generar fácilmente documentación API precisa y fácil de usar que puede ayudar a reducir el tiempo y el esfuerzo necesarios para crear la documentación. Además, Swagger proporciona una variedad de funciones que pueden ayudar a mejorar la eficiencia y la eficacia del proceso de desarrollo, incluida la documentación interactiva, la generación de código y herramientas de testing. Al seguir los pasos descritos en este artículo, los desarrolladores pueden integrar Swagger rápida y fácilmente en sus aplicaciones Spring Boot y comenzar a documentar sus API REST de manera clara y concisa.
Te puede interesar
Consumir servicios Rest con Apache HttpClient
Apache HttpClient es una biblioteca de Java. En este artículo se demostrará como consumir servicios Rest con Apache HttpClient.
Palabras reservadas en Java
Las palabras reservadas en Java son un componente crucial de la sintaxis del lenguaje para formar los bloques básicos del lenguaje.
Crear un arquetipo de Maven
Crear un arquetipo de Maven permite generar nuevos proyectos de similares caracteríticas a partir de una plantilla.
Convenciones de nombres en API Rest
Las convenciones de nombres en API REST son fundamentales para facilitar la comprensión de cómo interactuar con la API.