O Knife4j é uma solução aprimorada para integrar a documentação da API Swagger em frameworks Java MVC. Anteriormente conhecido como swagger-bootstrap-ui, o Knife4j evoluiu de um mero tema para o Swagger UI para se tornar uma solução abrangente para serviços de documentação de API Swagger, com foco não apenas na interface do usuário, mas também em funcionalidades mais amplas.

Para integrar o Knife4j ao seu projeto Spring Boot, siga estas etapas:

1. Adicionar Dependência

Inclua a seguinte dependência no seu arquivo pom.xml:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2. Configurar o Arquivo YAML

Adicione as seguintes configurações ao seu arquivo application.yml (ou application.properties):

knife4j:
  # Habilita ou desabilita o Swagger
  enabled: true
  # Prefixo para os caminhos das APIs
  pathMapping: /api-docs
  # Habilita o modo aprimorado do Knife4j (padrão: false)
  enhance: true

Para mais detalhes sobre as configurações do modo aprimorado, consulte a documentação oficial.

3. Configurar o Knife4j

Crie uma classe de configuração para o Knife4j:

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.annotations.ApiOperation;
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.oas.models.SecuritySchemes;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.spi.service.contexts.SecurityContext;
import java.util.ArrayList;
import java.util.List;

@Configuration
@EnableKnife4j
public class SwaggerConfiguration {

    @Value("${knife4j.enabled}")
    private boolean swaggerEnabled;

    @Value("${knife4j.pathMapping}")
    private String apiPathPrefix;

    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.OAS_30)
                .enable(swaggerEnabled)
                .apiInfo(buildApiInfo())
                .groupName("v1") // Nome do grupo da API
                .select()
                // Seleciona APIs anotadas com @ApiOperation
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // Ou selecione todas as APIs em um pacote específico:
                // .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .securityContexts(buildSecurityContexts())
                .pathMapping(apiPathPrefix);
    }

    private List<SecurityContext> buildSecurityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .operationSelector(operationContext -> operationContext.requestMappingPattern().matches("/api/.*")) // Exemplo: aplica a todas as rotas que começam com /api/
                        .build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope globalScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = {globalScope};
        List<SecurityReference> securityReferences = new ArrayList<>();
        // Assume que o token está sendo passado no cabeçalho "Authorization"
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    private ApiInfo buildApiInfo() {
        return new ApiInfoBuilder()
                .title("Documentação da API do Sistema de Gerenciamento")
                .description("API para gerenciamento de usuários e recursos.")
                .contact(new Contact("Desenvolvedores", null, "dev@example.com"))
                .version("1.0.0")
                .build();
    }
}

4. Liberar Requisições do Knife4j

Configure o Spring MVC para permitir o acesso aos recursos do Knife4j:

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // Libera o acesso à interface do Swagger UI
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // Libera o acesso aos arquivos webjars
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        // Libera o acesso à interface do Knife4j
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

5. Anotar Interfaces com Comandos do Knife4j

Use as anotações do Swagger e do Knife4j para documentar seus controladores e modelos:

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.web.bind.annotation.*;

@Api(tags = "Gerenciamento de Usuários")
@RestController
@RequestMapping("/users")
public class UserController {

    @ApiOperation(value = "Obtém informações do usuário por nome", response = String.class)
    @ApiImplicitParam(name = "userName", value = "Nome do usuário a ser buscado", required = true, dataType = "String", paramType = "query")
    @GetMapping("/getByName")
    public String getUserByName(@RequestParam("userName") String name) {
        return "User: " + name;
    }

    @ApiOperation(value = "Cria um novo usuário", response = String.class)
    @PostMapping("/create")
    public String createUser(@RequestBody UserDetails userDetails) {
        return "User " + userDetails.getName() + " created successfully.";
    }
}

Modelo de dados:

@ApiModel(description = "Detalhes do usuário")
@Data
public class UserDetails {

    @ApiModelProperty(value = "Nome do usuário", required = true)
    private String name;

    @ApiModelProperty(value = "Email do usuário", required = true)
    private String email;
}

6. Acessar a Página de Documentação

Após a configuração e execução da aplicação, acesse a documentação da API através do sgeuinte endereço:

http://localhost:8080/doc.html

(Substitua 8080 pela porta da sua aplicação, se for diferente).