Knife4j 简介

Knife4j 是一个增强的 Swagger 文档生成工具，提供了更加友好的界面和更多功能，使得 API 文档更加美观且易于使用。它是基于 Spring Boot 和 Swagger 进行封装的，因此非常适合 Spring Boot 项目。

使用步骤

第一步：添加依赖

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

第二步：配置 Swagger 配置类

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                //TODO 改成自己的包名
                .apis(RequestHandlerSelectors.basePackage("com.example.hac.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文档")
                .description("API 接口文档的描述信息")
                .version("1.0")
                .build();
    }
}

第三步：配置 application.yml

knife4j:
  enable: true  # 启用 Knife4j 功能 

springdoc:
  api-docs:
    enabled: true  # 启用 SpringDoc API 文档生成 
  swagger-ui:
    enabled: true  # 启用 Swagger UI 界面 

Knife4j 常用注解的列表

注解	作用	示例
@Api	标注在类上，用于描述该类的作用和功能，可以分组管理 API。	@Api(tags = "用户管理")
@ApiOperation	标注在方法上，用于描述一个具体的操作（HTTP 请求），包括操作的功能、描述和其他细节。	@ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
@ApiModel	标注在类上，用于描述一个 Model（实体类）的详细信息。	@ApiModel(value = "用户信息")
@ApiModelProperty	标注在实体类的属性上，用于描述属性的详细信息，如字段说明、示例值等。	@ApiModelProperty(value = "用户名字", example = "张三")
@ApiParam	标注在方法参数上，用于描述参数信息，如参数名称、类型、是否必填等。	@ApiParam(name = "id", value = "用户ID", required = true)
@ApiResponse	标注在方法上，用于描述单个 HTTP 响应。	@ApiResponse(code = 200, message = "请求成功")
@ApiResponses	标注在方法上，用于描述多个 HTTP 响应。	@ApiResponses({@ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 404, message = "未找到")})
@ApiImplicitParam	标注在方法上，用于描述单个隐式参数。	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "query")
@ApiImplicitParams	标注在方法上，用于描述多个隐式参数。	@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "query")})
@ApiIgnore	用于忽略某个类、方法或参数，使其不在 Swagger 文档中显示。	@ApiIgnore

案例

第一步：定义一个pojo

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(value = "用户信息")
public class User {
    @ApiModelProperty(value = "用户名字", example = "1")
    private String name;

    @ApiModelProperty(value = "用户年龄", example = "20")
    private String age;
}

第二步：编写controller service mapper

@RestController
@RequestMapping(value = "/users")
@Api(tags = "用户管理")
public class TestController {
    @Autowired
    private TestService testService;

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
    @GetMapping(value = "/{id}")
    public User getById(@PathVariable("id") int id) {
        return testService.getById(id);
    }
}

第三步：启动项目 访问：http://localhost:8080/doc.html

注意

可能会遇到这个错误Failed to start bean 'documentationPluginsBootstrapper';

原因：这个错误是因为 Spring Boot 2.6.0 中引入了新的路径模式匹配策略，而 Swagger 3.0.0 使用了旧的路径匹配策略。这导致了 documentationPluginsBootstrapper 的启动失败
解决方法1：
在application.yml中添加下面这

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

解决方法2：降低 Spring Boot 的版本

 <parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>2.4.5</version>
 </parent>

---

❤觉得有用的可以留个关注❤