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 para configurar Swagger y documentar nuestros web services RESTful:

springfox-swagger2: Esta dependencia se utiliza para generar los documentos API REST para web services RESTful. Es un proyecto de código abierto que proporciona la funcionalidad para documentar web services RESTful y sus endpoints.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

springfox-swagger-ui: Esta dependencia proporciona una interfaz de usuario para acceder a web services RESTful a través de un navegador web. Complementa springfox-swagger2 al ofrecer una interfaz fácil de usar para interactuar con los web services RESTful documentados.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Agregar la configuración mediante Docket

En Springfox, la clase Docket es un componente esencial para configurar y personalizar la documentación Swagger de una aplicación Spring Boot. Esta clase proporciona una forma de personalizar la apariencia, el comportamiento y el contenido de la documentación. Permite a los desarrolladores definir parámetros de operación de API globales, seleccionar rutas y API específicas para incluirlas en la documentación, y configurar los metadatos de la misma.

Pasos para Configurar la Documentación mediante Docket:

1. Crear una Clase Java Anotada con @Configuration y @EnableSwagger2:
   • Se debe crear una clase Java anotada con @Configuration y @EnableSwagger2. Esta clase será responsable de configurar la documentación Swagger para la aplicación Spring Boot.
2. Implementar un Método Anotado con @Bean:
   • Se debe implementar un método anotado con @Bean, por ejemplo, el método api(), que retornará un objeto Docket. En este método se especificará la ruta a los controladores de la API para que Swagger pueda localizarlos.
3. Implementar un Método que Retorne un Objeto ApiInfo:
   • Además, se debe implementar un método que retorne un objeto ApiInfo, por ejemplo, el método getApiInfo(), donde se especificarán atributos del API.

A continuación se muestra un ejemplo de código que ilustra la implementación de la configuración mediante la clase Docket del framework Springfox:

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()
					);
		}
	
}

El propósito del método select() en la clase Docket es especificar qué controladores y métodos deben incluirse en la documentación de la API. Devuelve una instancia de ApiSelectorBuilder, que permite filtrar los controladores y métodos según criterios específicos.

La clase ApiSelectorBuilder en Springfox proporciona métodos para seleccionar API y métodos que se incluirán en la documentación generada.

1. Método apis():
   • El método apis() nos permite controlar qué controladores se incluirán en la documentación. Se necesita un predicado como argumento para filtrar los controladores de solicitudes que se incluirán en la documentación.
2. Método paths():
   • El método paths() nos permite controlar qué endpoints específicos se incluirán en la documentación. También toma un predicado como argumento para filtrar las rutas que se incluirán en la documentación.

También es posible excluir ciertas partes del código de la documentación generada usando la anotación @ApiIgnore. La anotación @ApiIgnore se puede aplicar a nivel de método, tipo o parámetro. Así es como se puede utilizar:

1. A nivel de clase: Cuando se aplica a nivel de tipo, se ignorará toda la clase o tipo y su documentación asociada al generar la documentación API.

@ApiIgnore
@RestController
public class CustomerController {

	//methods...

}

2. A nivel de método: Cuando se aplica a nivel de método, el método anotado y su documentación asociada se ignorarán al generar la documentación de la API. Por ejemplo:

	@ApiIgnore
	@GetMapping("/customer")  
	public List<Customer> getCustomers() { 
		return new ArrayList<Customer>(customers.values()); 
	}

3. A nivel de parámetro: Cuando se aplica a nivel de parámetro, el parámetro anotado se excluirá de la documentación de la API. Por ejemplo:

    @PostMapping("/customer")  
    public String addCustomer(@RequestBody @ApiIgnore Customer customer) { 
        customers.put(customer.getId(), customer); 
        return "Cliente agregado correctamente."; 
    } 	

La clase ApiInfo en Springfox se utiliza para proporcionar metainformación sobre la API, como su título, descripción, versión, detalles de contacto e información de licencia. Permite personalizar y proporcionar detalles esenciales sobre su API, que luego se utilizan en la documentación de Swagger.

Para utilizar la clase ApiInfo, puede crear una instancia de ella y personalizar la metainformación sobre su API. A continuación se muestra un ejemplo de cómo se puede utilizar:

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import java.util.ArrayList;

// Create an instance of ApiInfo with customized meta-information
ApiInfo apiInfo = new ApiInfo(
    "API Title",
    "API Description",
    "1.0",
    "Terms of Service URL",
    new Contact("Contact Name", "Contact URL", "Contact Email"),
    "License",
    "License URL",
    new ArrayList<>()
);

El constructor ApiInfo recibe varios parámetros para definir los detalles de la API. Aquí hay una explicación detallada de cada uno de ellos:

• Título: permite especificar un título significativo para la API.
• Descripción: proporciona información adicional sobre el propósito y la funcionalidad de la API.
• Versión: ayuda a identificar la versión de la API que se está documentando.
• URL de Términos de Servicio: proporciona un enlace a los términos de servicio que se aplican al uso de la API.
• Contacto: Este parámetro es de tipo Contact y representa la información de contacto de la API. Incluye detalles como el nombre, URL y correo electrónico de la persona de contacto u organización responsable de la API.
• Licencia: normalmente incluye el nombre de la licencia bajo la cual se distribuye la API.
• URL de la Licencia: proporciona un enlace al texto completo de la licencia bajo la cual se distribuye la API.
• Extensiones de Proveedores: este parámetro es una colección de objetos VendorExtension. Permite la inclusión de extensiones adicionales específicas del proveedor en la documentación de la API.

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/customer-service/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/customer-service/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