Knife4j 生成 API 文档

文章目录

- [Knife4j 简介](#Knife4j 简介)
- 使用步骤
- [Knife4j 常用注解的列表](#Knife4j 常用注解的列表)
- 案例
- 注意

Knife4j 简介

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

使用步骤

第一步：添加依赖

xml 复制代码

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

第二步：配置 Swagger 配置类

java 复制代码

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

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

java 复制代码

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

java 复制代码

@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中添加下面这

yml 复制代码

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

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

xml 复制代码

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

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