Springboot 整合 Knife4j （API文档生成工具）

一、Knife4j 介绍

二、Springboot 整合 Knife4j

1、pom.xml中引入依赖包

2、在application.yml 中添加 Knife4j 相关配置

3、打开 Knife4j UI界面

三、关于Knife4j框架中常用的注解

1、@Api

2、@ApiOperation

3、@ApiOperationSupport(order = X)

4、@ApiImplicitParam

5、@ApiModel / @ApiModelProperty

四、支持接口调试

五、离线下载

一、Knife4j 介绍

Knife4j 是一个基于 Swagger 构建的开源 Java API 文档工具，主要包括两大核心功能：文档说明和在线调试。使用简单的配置和注解就可以节省写接口文档的时间了，舒服！😄😄😄

二、Springboot 整合 Knife4j

1、pom.xml 中引入依赖包

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

2、在 application.yml 中添加 Knife4j 相关配置

server:
  port: 5555


knife4j:
  enable: true
  openapi:
    title: 接口文档
    description: "接口文档生成"
    email: ""
    concat: admin
    url: https://docs.xiaominfo.com
    version: v4.0
    license: Apache 2.0
    license-url: https://stackoverflow.com/
    terms-of-service-url: https://stackoverflow.com/
    group:
      test1:
        group-name: 分组名称
        api-rule: package
        api-rule-resources:
          - com.example.springbootzy

3、打开 Knife4j UI界面

浏览器地址栏输入：http://127.0.0.1:服务端口号/doc.html

三、关于Knife4j框架中常用的注解

1、@Api

作用于Controller类上，通过此注解的tags属性，可以指定模块名称，并且模块名称前添加数字， Knife4j会根据这些数字将各个模块做升序排列。

@RequestMapping("/common")
@RestController
@Api(tags= "01 通用模块")
public class CommonController {

    @PostMapping("/queryByCondition")
    public String queryByCondition(@RequestBody QueryCondition queryCondition) {
        return "this is common demo";
    }
}


@RestController
@RequestMapping("/user")
@Api(tags= "02 用户模块")
public class UserController {

    @PostMapping("/queryUser")
    public String queryUser(@RequestBody QueryCondition queryCondition) {
        return "this is user demo";
    }
}


@Api(tags= "03 公司模块")
@RestController
@RequestMapping("/company")
public class CompanyController {

    @PostMapping("/queryCompany")
    public String queryCompany(@RequestBody QueryCondition queryCondition) {
        return "this is company demo";
    }
}

2、@ApiOperation

作用于 Controller 类中的方法上，用于描述 API 接口的功能和作用。

@RequestMapping("/common")
@RestController
@Api(tags= "01 通用模块")
public class CommonController {

    @ApiOperation("根据条件查询数据")
    @PostMapping("/queryByCondition")
    public String queryByCondition(@RequestBody QueryCondition queryCondition) {
        return "this is common demo";
    }
}

3、@ApiOperationSupport(order = X)

作用于 Controller 类中的方法上，通过此注解的 order 属性（int），可以指定排序序号。

@RequestMapping("/common")
@RestController
@Api(tags= "01 通用模块")
public class CommonController {

    @ApiOperation("根据条件查询数据")
    @ApiOperationSupport(order = 2)
    @PostMapping("/queryByCondition")
    public String queryByCondition(@RequestBody QueryCondition queryCondition) {
        return "this is common demo";
    }

    
    @ApiOperation("保存")
    @ApiOperationSupport(order = 3)
    @PostMapping("/add")
    public String add(@RequestBody QueryCondition queryCondition) {
        return "this is add";
    }

    
    @ApiOperation("更新")
    @ApiOperationSupport(order = 1)
    @PostMapping("/update")
    public String update(@RequestBody QueryCondition queryCondition) {
        return "this is update";
    }
}

4、@ApiImplicitParam

作用于 Controller 类中的方法上，用于描述方法入参的详细信息。


    @ApiOperation("根据主键ID查询")
    @ApiOperationSupport(order = 4)
    @ApiImplicitParam(name = "id", value = "主键ID", required = true, dataType = "Long", paramType = "path")
    @PostMapping("/queryById/{id}")
    public String queryById(@PathVariable Long id) {
        return "this is queryById";
    }

5、@ApiModel / @ApiModelProperty

@ApiModel：作用于 POJO 类上，描述该对象的作用。

@ApiModelProperty：作用于 POJO 类的属性上，描述参数信息。

@ApiModel("通用查询条件实体")
@Data
public class QueryCondition {

    @ApiModelProperty(value = "页码", required = true, example = "1")
    private Integer pageSize;

    @ApiModelProperty(value = "每页显示数量", required = true, example = "20")
    private Integer pageNum;

    @ApiModelProperty(value = "主键ID", required = false, example = "1",dataType ="Long")
    private Long id;

    @ApiModelProperty(value = "名称", required = false, example = "张三")
    private String name;
}