Para integrar Swagger2 en un proyecto Spring Boot, se requieren varios pasos que implican la adición de dependencias, la creación de una clase de configuración y el desarrollo de controladores con anotaciones. A continuación, se describe el proceso con ejemplos de código modificados para ilustrar la integración.

1. Dependencias de Maven

Primero, es necesaroi incluir las dependencias de Springfox Swagger2 y la interfaz de usuario correspondiente en el archivo pom.xml.

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

Además, se debe agregar el starter web de Spring Boot para soportar aplicaciones web.

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

2. Clase de Configuración para Swagger

Se crea una clase de configuración que habilita Swagger2 y define los recursos estáticos necesarios para aceder a la interfaz de usuario. Esto soluciona problemas comunes como errores 404 al intentar ver la documentación.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
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
@ComponentScan(basePackages = {"swagger2.ejemplo"})
@EnableWebMvc
public class ConfiguracionSwagger implements WebMvcConfigurer {
    @Bean
    public Docket configurarDocumentacion() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(informacionApi())
                .select()
                .paths(PathsSelectors.any())
                .build();
    }

    private ApiInfo informacionApi() {
        Contact contacto = new Contact("Nombre", "http://ejemplo.com", "contacto@ejemplo.com");
        return new ApiInfoBuilder()
                .title("Documentación de API con Swagger2")
                .termsOfServiceUrl("http://ejemplo.com/terminos")
                .description("Ejemplo de documentación para endpoints REST")
                .contact(contacto)
                .version("1.0")
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

3. Desarrollo de un Controlador de Ejemplo

Se implementa un controlador REST con métodos que pueden incluir anotaciones de Swagger para documentarlos. En este caso, un método tiene anotaciones y otro no, para demostrar cómo controlar la visibilidad.

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.util.Assert;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1")
public class ControladorDemo {

    @ApiOperation(value = "Saludo personalizado", notes = "Retorna un saludo con el nombre proporcionado")
    @ApiImplicitParam(name = "nombre", value = "Nombre del usuario", paramType = "query", required = true)
    @GetMapping("/saludar")
    public String saludar(String nombre) {
        Assert.isTrue(!StringUtils.isEmpty(nombre), "El nombre no puede estar vacío");
        return "¡Hola " + nombre + "! Encantado de saludarte.";
    }

    @GetMapping("/reservado")
    public String endpointReservado(String nombre) {
        Assert.isTrue(!StringUtils.isEmpty(nombre), "El nombre es obligatorio");
        return "Operación no disponible para " + nombre;
    }
}

4. Personalización de la Visibilidad de Endpoints

Para evitar que ciertos endpoints aparezcan en la documentación de Swagger, se puede modificar la configuración para encluir solo rutas específicas. Esto se logra definiendo un predicado con expresiones regulares.

import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
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;

import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"swagger2.ejemplo"})
@EnableWebMvc
public class ConfiguracionSwagger implements WebMvcConfigurer {
    @Bean
    public Docket configurarDocumentacion() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(informacionApi())
                .select()
                .paths(filtrarRutas())
                .build();
    }

    private Predicate<String> filtrarRutas() {
        // Ejemplo: solo incluir la ruta "/api/v1/saludar"
        return or(regex("/api/v1/saludar"));
    }

    private ApiInfo informacionApi() {
        Contact contacto = new Contact("Nombre", "http://ejemplo.com", "contacto@ejemplo.com");
        return new ApiInfoBuilder()
                .title("Documentación de API con Swagger2")
                .termsOfServiceUrl("http://ejemplo.com/terminos")
                .description("Ejemplo de documentación para endpoints REST")
                .contact(contacto)
                .version("1.0")
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

Al acceder a http://localhost:8080/swagger-ui.html, solo se mostrarán los endpoints que coincidan con el filtro definido, permitiendo controlar la exposición de la API en la documentación.