Adicionando Dependências do Swagger

Para iniciar a integração, adicione as dependências do Springfox ao seu arquivo pom.xml. A versão 2.9.2 é amplamente utilizada para projetos Spring Boot 2.x.

<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>

Configuração de Múltiplos Grupos

Em arquiteturas modulares, é necessário separar a documentação por grupos de controladores. A classe de configuração abaixo demonstra como criar múltiplos grupos (Grupo A e Grupo B), filtrando os caminhos e habilitando a documentação via propriedades externas.

import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 SwaggerMultiModuleConfig {

    @Value("${custom.swagger.enabled}")
    private boolean isSwaggerEnabled;

    private ApiInfo buildApiInfo() {
        return new ApiInfoBuilder()
                .title("API de Exemplo")
                .description("Documentação gerada para o projeto de teste")
                .contact(new Contact("Equipe de Desenvolvimento", "https://exemplo.com", "dev@exemplo.com"))
                .version("2.0.0")
                .build();
    }

    @Bean("grupoA")
    public Docket grupoAApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Grupo A")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.ant("/api/grupoA/**"))
                .build()
                .apiInfo(buildApiInfo())
                .enable(isSwaggerEnabled);
    }

    @Bean("grupoB")
    public Docket grupoBApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Grupo B")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.ant("/api/grupoB/**"))
                .build()
                .apiInfo(buildApiInfo())
                .enable(isSwaggerEnabled);
    }
}

Configuração de Codificação UTF-8

Para evitar problemas de rnederização de caracteres especiais e acentos na interface do Swagger, é fundamental forçar a codificação UTF-8 nas configurações do servidor e do Spring. Adicione as seguintse propriedades ao seu application.yml:

server:
  port: 8080
  tomcat:
    uri-encoding: UTF-8
  servlet:
    context-path: /api-docs

spring:
  http:
    encoding:
      charset: UTF-8
      force: true
      enabled: true

custom:
  swagger:
    enabled: true

Após essas configurações, a interface pode ser acessada através do endpoint /api-docs/swagger-ui.html.

Resolução de Conflitos com MyBatis e MyBatis-Plus

Um problema comum ao integrar o Swagger com MyBatis ou MyBatis-Plus ocorre quando a classe principle da aplicação utiliza a anotação @ComponentScan de forma ampla. Isso pode causar conflitos no escaneamento de pacotes, impedindo que o Swagger localize corretamente os controladores REST.

Para resolver essa falha de escaneamento, remova o @ComponentScan genérico da classe principal e utilize estritamente a anotação @MapperScan para apontar diretamente para os pacotes que contêm as interfaces de mapeamento do MyBatis. Isso isola a camada de persistência e permite que o Spring Boot escaneie os controladores do Swagger sem interferências.