目录
一、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.springbootzy3、打开 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;
}
四、支持接口调试
调用接口需要传 Token 的时候，可以在【全局参数配置】中添加 Token（或叫：Authorization，具体看自己项目定义）：
五、离线下载
