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 中引入依赖包

                    com.github.xiaoymin            knife4j-openapi2-spring-boot-starter            4.4.0        

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

server:  port: 5555knife4j:  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("通用查询条件实体")@Datapublic 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;}

四、支持接口调试

调用接口需要传 Token 的时候，可以在【全局参数配置】中添加 Token（或叫：Authorization，具体看自己项目定义）：

五、离线下载

---