O propósito do swagger não será abordado neste guia. Este documento tem como objetivo fornecer uma introdução prática à geração de docuemntação de APIs utilizando swagger, destacando as vantagens da versão 3.

Dependências

A inclusão das dependências está relacionada com a versão do spring-boot-starter-parent. A versão encorreta do pacote spring-plugin-core pode causar falhas na execução do projeto.

Versão 2.1.x

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
    <exclusions>
        <exclusion>
            <artifactId>spring-plugin-core</artifactId>
            <groupId>org.springframework.plugin</groupId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.plugin</groupId>
    <artifactId>spring-plugin-core</artifactId>
    <version>2.0.0.RELEASE</version>
</dependency>

Versão 2.3.x

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

Configruação

Classe de Inicialização

Adicione a anotação @EnableOpenApi à classe principal. Embora testes indiquem que o sistema funciona sem ela, sua inclusão é uma prática recomendada:

@EnableOpenApi
@SpringBootApplication
public class SwaggerDemoApplication {

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

Configuração do Swagger

A configuração pode controlar a exposição da documentação com base no ambiente e perfis do projeto:

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket initDocket(Environment env) {
        // Define os perfis onde a documentação será exibida
        Profiles profile = Profiles.of("dev", "test");
        boolean flag = env.acceptsProfiles(profile);
        
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Documentação da API - Swagger Demo")
                .description("Documentação técnica da API de demonstração")
                .contact(new Contact("Equipe de Desenvolvimento", "http://www.exemplo.com", "suporte@exemplo.com"))
                .version("1.0")
                .build();
    }
}

Também é possível controlar a visibilidade através do arquivo de configuração:

springfox.documentation.auto-startup = false

Anotações Comuns

Em Classes

@Api(): Indica que a classe é um recurso Swagger

• tags: Descrição do conteúdo
• value: Descrição substituída por tags

Em Métodos

@ApiOperation(): Descreve o método

• value: Descrição do método
• notes: Comentários adicionais
• response: Objeto de retorno
• tags: Agrupa métodos separadamente

Em Parâmetros de Método

@ApiParam(): Descreve parâmetros de método (útil em requisições POST)

• name: Nome do parâmetro
• value: Descrição do parâmetro
• required: Se é obrigatório

@ApiImplicitParam: Descreve parâmetros de método (útil em requisições GET e POST)

• name: Nome do parâmetro
• value: Descrição breve
• required: Se é obrigatório
• dataType: Tipo do parâmetro
• paramType: Tipo de entrada (path, query, body, header, form)

Em Entidades

@ApiModel: Descreve informações de um modelo

• value: Apelido do modelo
• description: Descrição detalhada

@ApiModelProperty: Descreve propriedades de um modelo

• value: Descrição breve
• example: Valor de exemplo
• required: Se é obrigatório

Parâmetros de Header

@ApiImplicitParams({
    @ApiImplicitParam(paramType="header", name="AUTH_TOKEN", dataType="String", required=true, value="Token de autenticação")
})

Parâmetros de Arquivo

Para upload de arquivos, utilize a anotação @RequestPart:

@ApiOperation(value = "Endpoint para upload de arquivos", notes = "Envia um arquivo para o servidor")
@ApiImplicitParams({
    @ApiImplicitParam(name = "uploader", value = "Nome do usuário que está enviando o arquivo")
})
@PostMapping(value = "/upload")
public String uploadFile(@RequestParam("uploader") String uploader, @RequestPart("file") MultipartFile file) {
    // Lógica de processamento do arquivo
}

Configuração de Interceptors

Se o projeto utiliza interceptores, é necessário liberar os seguintes caminhos:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private AuthInterceptor authInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns("/**/swagger-ui/**")
                .excludePathPatterns("/**/swagger-resources/**")
                .excludePathPatterns("/**/v3/**");
    }
}

Endereços de Acesso à Documentação

• Versão 2.9.x: http://ip:porta/{context-path}/swagger-ui.html
• Versão 3.0.x: http://ip:porta/{context-path}/swagger-ui/index.html
• Swagger 3 com Knife4j: http://ip:porta/{context-path}/doc.html

Tratamento de Respostas Padronizadas

Para projetos que utilizam classes de encapsulamento de resposta como ApiResponse, adicione o tipo genérico no retorno do método:

public ApiResponse<Usuario> buscarUsuarioPorId(Long id) {
    // Lógica de busca
}

Exemplo Completo

Um projeto de demonstração completo está disponível no repositório: swagger3-demo