1、Knife4j介绍：
1.1 介绍：
官网地址: https://doc.xiaominfo.com
Knife4j是基于SpringBoot构建的一个文档生成工具，它可以让开发者为我们的应用生成在线API文档； 目的是可以更加方便的基于API文档进行测试。
生成的文档还可以导出，然后给到前端开发团队，前端开发团队可以基于API接口写具体的调用。 是基于Swagger框架实现的。
1.2 优点：
Knife4j的优点 Knife4j 功能强大，易于操作。 Knife4j 的UI界面非常美观，使用流畅。 Knife4j 可以高度定制化，让其符合你的项目需求。
2、案例
2.1 依赖
在Spring Boot 2.0 项目中，使用Knife4j需要添加依赖 knife4j-openapi2-spring-boot-starter：
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
2.2.配置文件
application.yml
knife4j:
enable: true
openapi:
title: hello模块文档
description: "hello描述"
email: 123@foxmail.com
concat: sss
url: https://www.zhouzz.com
version: v2.0
group:
test1:
group-name: hello组名
api-rule: package
api-rule-resources:
- com.zhouzz.knife.controller
2.3 常用注解
2.3.1 @api
在控制器类上添加@Api注解，并配置tags属性，可以指定模块名称，例如：
@Slf4j
@Api(tags = "hello模块") //模块名称
@RestController
@RequestMapping("/hello")
public class HelloController {
}
2.3.2 @ApiOperation
在处理请求的方法上添加@ApiOperation注解可以配置某个业务功能名称，例如：
@ApiOperation("info方法")
@ApiOperationSupport(order = 14)
@PostMapping(value = "/info")
public Object info(@RequestBody User user) {
log.info("info method param:{}", user);
Map<String, Object> map = new HashMap<>();
user.setUsername("lisi");
user.setDate(new Date());
map.put("user", user);
return map;
}
2.3.3 @ApiOperationSupport
@ApiOperationSupport注解：用于指定功能前后序号
当需要指定各业务在API文档中的显示顺序时，可以在处理请求的方法上添加@ApiOperationSupport注解，配置此注解的order属性，最终在显示API文档时，会根据order属性值升序排列
通常，建议以上配置的order值至少是2位的数字，并且有预留位置，例如1019之间的都是增加数据的业务，2029之间的都是删除数据的业务，3039之间都是修改数据的业务，4049之间都是查询数据的业务。
2.3.4 @ApiModelProperty
@ApiModelProperty： 用于说明引用类型参数的类型。
如果控制器处理请求的方法的参数是自定义的封装类型，可以在封装类型的属性上添加@ApiModelProperty来配置参数在文档中的显示
@Data
public class User implements Serializable {
@ApiModelProperty(value = "用户ID")
private Long id;
@ApiModelProperty(value = "用户名称")
private String username;
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
@ApiModelProperty(value = "日期")
private Date date;
}
以上 @ApiModelProperty 除了可以配置参数在API文档中显示的名称以外，还可以配置是否必须，例如：
@ApiModelProperty(value = "用户名", required = true)
另外，还可以配置参数类型等，但是，并不是必须配置，通常框架可以正常自动识别。
对于部分名称可能比较特殊（一般人看不懂的名称）的属性，或者对值的规范性要求比较明确（例如某些取值为0或1）的属性，可以列举示例，使得查看API文档的人可以参考，例如：
@ApiModelProperty(value = "用户名", required = true, example = "admin")
2.3.5 @ApiImplicitParam
@ApiImplicitParam： 用于说明基本类型参数
添加在控制器类中处理请求的方法上的注解，主要用于配置非封装(非XxxDTO/XxxParam的参数)的参数
参数说明:
- name：指定参数名称（参数变量名）
- value：配置参数名称
- dataType：配置数据类型
- required：配置是否必须提交此请求参数
- example：配置参数的示例值
注意：一旦使用此注解，各个参数的数据类型默认都会显示String，可以通过dataType指定数据类型
@ApiImplicitParam(name = "id", value = "微博", required=true, dataType = "int")
public WeiboDetailVO selectById(int id){...}
2.3.6 @ApiImplicitParams
@ApiImplicitParams: 说明多个基本类型参数
(类似上边的@ApiImplicitParam注解)
添加在控制器类中处理请求的方法上的注解，当方法有多个非封装的参数时，在方法上添加此注解，并在注解内部通过@ApiImplicitParam数组配置多个参数。
/**微博详情页功能*/
@GetMapping("selectById")
@ApiOperation(value = "微博详情功能")
@ApiImplicitParams(value = {
@ApiImplicitParam(name = "id", value = "微博", required=true, dataType = "int"),
@ApiImplicitParam(name = "username", value = "用户名", required=true)
})
// 额外增加username参数，仅仅用于测试
public WeiboDetailVO selectById(int id, String username){
return weiboMapper.selectById(id);
}
2.3.7 @ApiIgnore注解
@ApiIgnore注解: 忽略某个方法的参数。
添加在处理请求的方法的参数上，用于表示API文档框架应该忽略此参数
@ApiOperation(value = "hello4测试方法")//功能名称
@ApiOperationSupport(order = 101)//在文档中的顺序
@ApiImplicitParams({@ApiImplicitParam(name = "x", value = "x坐标", required = true, dataType = "int", example = "10"),
@ApiImplicitParam(name = "y", value = "y坐标", required = true, dataType = "int", example = "10")})//基本类型参数
@GetMapping("/hello4")
public String hello4(int x, int y, @ApiIgnore int z) {
return "你好：" + (x + y);
}
评论区