一、Knife4j介绍:
1.1.介绍:
Knife4j是基于SpringBoot构建的一个文档生成工具,它可以让开发者为我们的应用生成在线API文档; 目的是可以更加方便的基于API文档进行测试。 生成的文档还可以导出,然后给到前端开发团队,前端开发团队可以基于API接口写具体的调用。 是基于Swagger框架实现的。
1.2.优点:
1 Knife4j的优点 Knife4j 功能强大,易于操作。 Knife4j 的UI界面非常美观,使用流畅。 Knife4j 可以高度定制化,让其符合你的项目需求。
二、案例:
2.1.依赖:
在Spring Boot项目中,使用Knife4j需要添加依赖knife4j-spring-boot-starter:
<!--添加Knife4j依赖-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
<!--<version>4.3.0</version>-->
</dependency>
2.2.配置类:
然后,需要添加配置,则在boot-demo项目的cn.tedu.boot.demo.config包下创建Knife4jConfig类:
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
private String basePackage = "com.zyq.knife4j.controller";/**指定Controller包路径*/
private String groupName = "zyq-kni4j-demo";/**分组名称*/
private String host = "http://java.zyq.cn";/**主机名 */
private String title = "zyq-kni4j-demo测试项目在线API文档";/**标题 */
private String description = "zyq-kni4j-demo测试项目在线API文档";/**简介*/
private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";/**条款URL */
private String contactName = "Java教学研发部";/**联系人*/
private String contactUrl = "http://java.zyq.cn";/**联系网址*/
private String contactEmail = "zhaoYong1230@126.com";/**联系邮箱 */
private String version = "1.0.0";/**版本号*/
@Autowired(required = false)
private OpenApiExtensionResolver openApiExtensionResolver;
//配置Swagger2的Docket的Bean实例
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.host(host)
//apiInfo():配置 API 的一些基本信息,比如:文档标题,描述,文档版本号
.apiInfo(apiInfo())
//分组名称
.groupName(groupName)
// select():生成 API 文档的选择器,用于指定要生成哪些 API 文档
.select()
// apis():指定要生成哪个包下的 API 文档
.apis(RequestHandlerSelectors.basePackage(basePackage))
//paths():指定要生成哪个 URL 匹配模式下的 API 文档。这里使用PathSelectors.any(),表示生成所有的 API 文档。
.paths(PathSelectors.any())
.build()//build():生成 Docket 实例
.extensions( openApiExtensionResolver.buildExtensions(groupName) );
return docket; //.extensions()扩展
}
//配置Swagger2的ApiInfo的Bean实例(文档标题title,文档描述description,文档版本号version)
private ApiInfo apiInfo() { return new //termsOfServiceUrl服务条款URL
ApiInfoBuilder().title(title).description(description).termsOfServiceUrl(termsOfServiceUrl)
//文档联系人(作者)信息
.contact(new Contact(contactName, contactUrl, contactEmail)).version(version).build();
}
}
注意:必须修改以上配置中的包名,保证是当前项目中控制器类所在的包!其它各项均可不修改,以上配置代码可以从Knife4j的官网找到!
2.3.配置启用knife4j:
最后,还需要在application.yaml配置文件中开启Knife4j的增强模式:
完成后,启动项目,在浏览器中访问 http://localhost:8080/doc.html 即可查看当前项目的API文档。
2.4.常用注解:
1.@api 模块名称配置
在控制器类上添加@Api注解,并配置tags属性,可以指定模块名称,例如:
文档显示效果:
2.@ApiOperation注解: 标注在controller类上的方法上,标识模块的小功能名称
在处理请求的方法上添加@ApiOperation注解可以配置某个业务功能名称,例如:
效果如下:
3.@ApiOperationSupport注解:用于指定功能前后序号
当需要指定各业务在API文档中的显示顺序时,可以在处理请求的方法上添加@ApiOperationSupport注解,配置此注解的order属性,最终在显示API文档时,会根据order属性值升序排列,例如:
通常,建议以上配置的order值至少是2位的数字,并且有预留位置,例如10~19之间的都是增加数据的业务,20~29之间的都是删除数据的业务,30~39之间都是修改数据的业务,40~49之间都是查询数据的业务。
效果如下:
4.ApiModelProperty: 用于说明引用类型参数的类型。
如果控制器处理请求的方法的参数是自定义的封装类型,可以在封装类型的属性上添加@ApiModelProperty来配置参数在文档中的显示,例如:
以上@ApiModelProperty除了可以配置参数在API文档中显示的名称以外,还可以配置是否必须,例如:
@ApiModelProperty(value = "用户名", required = true)
另外,还可以配置参数类型等,但是,并不是必须配置,通常框架可以正常自动识别。
对于部分名称可能比较特殊(一般人看不懂的名称)的属性,或者对值的规范性要求比较明确(例如某些取值为0或1)的属性,可以列举示例,使得查看API文档的人可以参考,例如:
@ApiModelProperty(value = "用户名", required = true, example = "admin")
除以配置请求参数以外,此属性还可以用于响应结果的类型,例如:
public class JsonResult<T> implements Serializable {
@ApiModelProperty("业务状态码")
private Integer state;
@ApiModelProperty("消息")
private String message;
@ApiModelProperty("数据")
private T data;
// ......
}
如果以上private T data;的实际值也需要添加说明,则在对应的类的属性上继续使用@ApiModelProperty配置即可!需要注意:此处data属性可以是任意数据类型,必须声明为泛型,不可以是Object,否则将无法应用@ApiModelProperty的配置。
另外,当添加在响应的类型的属性上时,还可以在@ApiModelProperty注解中配置position属性,用于设置各属性在响应的JSON中的显示顺序,例如:
@ApiModelProperty(value = "业务状态码", position = 5)
5.@ApiImplicitParam: 用于说明基本类型参数
添加在控制器类中处理请求的方法上的注解,主要用于配置非封装(非XxxDTO/XxxParam的参数)的参数
参数说明:
name:指定参数名称(参数变量名)
value:配置参数名称
dataType:配置数据类型
required:配置是否必须提交此请求参数
example:配置参数的示例值
注意:一旦使用此注解,各个参数的数据类型默认都会显示String,可以通过dataType指定数据类型
代码示例(此处以另外一个案例“根据id查询微博功能”为例)
@ApiImplicitParam(name = "id", value = "微博", required=true, dataType = "int")
public WeiboDetailVO selectById(int id){...}
本案例中的相关代码,效果如下:
6.@ApiImplicitParams: 说明多个基本类型参数
(类似上边的@ApiImplicitParam注解)
添加在控制器类中处理请求的方法上的注解,当方法有多个非封装的参数时,在方法上添加此注解,并在注解内部通过@ApiImplicitParam数组配置多个参数。
代码示例(此处以另外一个案例“根据id查询微博功能”为例)
/**微博详情页功能*/
@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);
}
本案例中的相关代码,效果如下:
7.@ApiIgnore注解: 忽略某个方法的参数。
添加在处理请求的方法的参数上,用于表示API文档框架应该忽略此参数
代码示例
// 参数中添加@ApiIgnore注解
@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) {
return "你好:"+(x+y);
}
如果上边方法添加一个int z参数则效果如下:
然后给方法参数int z 左边添加注解@ApiIgnore,效果如下:
三、完整代码如下:
3.1.依赖:
pom.xml文件中:
<properties>
<java.version>1.8</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.build.outputEncoding>UTF-8</project.build.outputEncoding>
<spring-boot.version>2.6.13</spring-boot.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>${spring-boot.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<version>${spring-boot.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<version>${spring-boot.version}</version>
<scope>test</scope>
</dependency>
<dependency><!--热部署-->
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-devtools</artifactId>
<scope>runtime</scope>
<optional>true</optional>
<version>${spring-boot.version}</version>
</dependency>
<dependency><!--工具类-->
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.1</version>
</dependency>
<!--引入Lombok依赖-->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.32</version>
</dependency>
<!--添加Knife4j依赖-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
<!--<version>4.3.0</version>-->
</dependency>
</dependencies>
3.2.配置文件:
application.yaml中:
# 解决循环依赖的问题
spring:
main:
allow-circular-references: true
mvc:
pathmatch:
matching-strategy: ant_path_matcher
#knife4j配置
knife4j:
# 是否开启增强模式
enable: true
# log4j配置
logging:
level:
root: INFO
# root: WARN
com:
zyq:
kni4j: INFO
server:
port: 8080
3.3.knife4j的配置类:
package com.zyq.knife4j.config;
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import org.springframework.beans.factory.annotation.Autowired;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig { /**【重要】指定Controller包路径*/
private String basePackage = "com.zyq.knife4j.controller";
private String groupName = "zyq-kni4j-demo"; /**分组名称*/
private String host = "http://java.zyq.cn"; /**主机名 */
private String title = "zyq-kni4j-demo测试项目在线API文档";/**标题 */
private String description = "zyq-kni4j-demo测试项目在线API文档";/**简介*/
private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";//条款URL
private String contactName = "Java教学研发部";/**联系人*/
private String contactUrl = "http://java.zyq.cn"; /**联系网址*/
private String contactEmail = "zhaoYong1230@126.com";/**联系邮箱 */
private String version = "1.0.0";/**版本号*/
@Autowired(required = false)
private OpenApiExtensionResolver openApiExtensionResolver;
//配置Swagger2的Docket的Bean实例
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(host)
//apiInfo():配置 API 的一些基本信息,比如:文档标题,描述,文档版本号
.apiInfo(apiInfo()) .groupName(groupName)//分组名称
.select()// select():生成 API 文档的选择器,用于指定要生成哪些 API 文档
// apis():指定要生成哪个包下的 API 文档
.apis(RequestHandlerSelectors.basePackage(basePackage))
//paths():指定要生成哪个 URL 匹配模式下的 API 文档。这里使用PathSelectors.any(),表示生成所有的 API 文档。
.paths(PathSelectors.any()) .build()//build():生成 Docket 实例
.extensions( openApiExtensionResolver.buildExtensions(groupName) );
return docket; //.extensions()扩展
}
//配置Swagger2的ApiInfo的Bean实例(文档标题,文档描述,文档版本号)
private ApiInfo apiInfo() { return new //termsOfServiceUrl服务条款URL
ApiInfoBuilder().title(title).description(description).termsOfServiceUrl(termsOfServiceUrl)
//文档联系人(作者)信息
.contact(new Contact(contactName, contactUrl, contactEmail)).version(version).build();
}
}
3.4.实体类User:
package com.zyq.knife4j.pojo.dto;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;
@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
//@Accessors(chain = true,fluent = true)
//启动lombok的链式编程,fluent = true表示让get和set方法没有set和get单词
public class User {
@ApiModelProperty(value = "用户编号", required = false, example = "1001")
private Integer id;
@ApiModelProperty(value = "用户名", required = true, example = "赵云")
private String name;
@ApiModelProperty(value = "年龄", required = true, example = "50")
private Integer age;
public User(String name, Integer age) {
this.name = name;
this.age = age;
}
}
//VO(View/Value Object)—— 视图对象
//DTO(Data Transfer Object)—— 数据传输对象
//BO(Business Object)—— 业务对象
//PO(Persistent Object)—— 持久对象
//DO(Data/Domain Object)—— 数据/领域对象
//POJO(Plain Old/Ordinary Java Object)—— 以上模型的统称
3.5.HelloController
package com.zyq.knife4j.controller;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import com.zyq.knife4j.pojo.dto.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
@RestController
@Api(tags = "hello测试模块")//模块名称
public class HelloController { // http://localhost:8080/doc.html
// Knife4jConfig的String basePackage 要指定controller类的路径,否则doc.html没作用
@ApiOperation(value = "hello测试方法")//功能名称
@ApiOperationSupport(order = 103)//在文档中的顺序
@GetMapping("/hello")
public String hello() { return "hello"; }
@ApiOperation(value = "hello2测试方法")
@ApiOperationSupport(order = 102)
@PostMapping("/hello2")
public String hello2(User user) { return "你好:"+user.getName(); }
@ApiOperation(value = "hello3测试方法")//功能名称
@ApiOperationSupport(order = 101)//在文档中的顺序
@ApiImplicitParam(name="x" ,value="编号",required = true,dataType = "int",example = "10")//基本类型参数
@GetMapping("/hello3")
public String hello3(int x) { return "你好:"+x; }
@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); }
}