Swagger documentando nuestro API REST

Swagger es una herramienta que nos permite documentar de una forma sencilla nuestras APIs REST hoy por hoy se ha convertido en uno de los standares de facto a la hora de trabajar . Cada día publicamos un mayor número de APIs REST y lo lógico es que publiquemos una documentación clara de como trabajar con ellas. Swagger nos permite hacerlo de una forma muy rápida y directa.

Vamos a ver un ejemplo, para ello partiremos de un proyecto de Spring boot que tiene un servicio que devuelve una lista de personas. Las dependencias de Maven son:

<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>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
 
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
    </dependencies>

Spring @RestController

En ellas podemos ver como hemos incluido las nuevas librerías. El siguiente paso es definir un servicio REST con la anotación @RestController.

package com.arquitecturajava.rest;

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ControladorPersona {

	@GetMapping("/personas")
	public List<Persona> findAll() {

		List<Persona> lista= new ArrayLis<Persona>();
		lista.add(new Persona("pepe","perez",25));
		lista.add(new Persona("juan","sanchez",35));
		lista.add(new Persona("ana","gomez",25));
		return lista;
	}

}

 Configuración de Spring

Es momento de configurar la herramienta  para que nos genere una documentación del API REST.Para ello añadimos un nuevo fichero de configuración de Spring.

package com.arquitecturajava.rest1;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.regex;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

	 @Bean
	    public Docket productApi() {
	        return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.arquitecturajava.rest"))
	             .paths(regex("/personas.*"))
	             .build();
	    }

}

Aquí configuramos swagger para que publique documentación para la url que publicamos en este caso nuestra url de /personas. Nos queda por ver el fichero de configuración principal de Spring framework que importará el de Swagger.

package com.arquitecturajava.rest;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Import;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@SpringBootApplication
@Import(SwaggerConfiguration.class)
public class RestApplication implements WebMvcConfigurer{

	public static void main(String[] args) {
		SpringApplication.run(RestApplication.class, args);
	}

	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {

	       registry.addResourceHandler("swagger-ui.html")
	                .addResourceLocations("classpath:/META-INF/resources/");

	}
}

Swagger y documentación

Arrancamos la aplicación con Spring Boot y accederemos de forma directa a la url de personas que nos mostrará la lista de personas.

Hasta aquí todo es lo habitual , sin embargo si miramos los ficheros de log de Spring boot podremos ver que se han publicado más urls.

Dos de las urls más importantes de swagger son /v2/api-docs  que publica la documentación en formato json . Si echamos un vistazo a la url recibiremos algo como :

En principio es una información que nos puede parecer extraña. Es suficiente abrirla con un visor de JSON para que la información nos quede mucho más clara:

Podemos ver claramente la definición de la operación y el tipo de objeto que devuelve, así como información adicional. Otra de las opciones que tenemos es acceder  a una vista web de la documentación mucho más amable utilizando la url /swagger-ui.html.

Entramos a controlador persona y vemos los métodos que tiene soportados:

Acabamos de documentar nuestro api REST con swagger.

Otros artículos relacionados:

1. REST HTTP return codes y sus curiosidades
2. Spring REST Service con @RestController
3. Arquitecturas REST y sus niveles
4. Spring Boot