Documentar un API REST con Swagger

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