Knife4j的简介

Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案，它的前身是上一篇文章中介绍的swagger-bootstrap-ui。swagger-bootstrap-ui的所有特性都会集中在Knife4j中，并且Knife4j也提供了很多非常方便的增强功能。

Knife4j的使用

1. 添加依赖包

knife4j已经引入了springfox，所以在使用时不用再次引入了。

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

2. 配置Swagger

创建Swagger配置类：

// 标明是配置类
@Configuration
// 开启Swagger功能
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 构建一个Docket Bean
     * @return
     */
    @Bean
    public Docket createRestApi() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                // 页面展示信息
                .apiInfo(apiInfo())
                // 返回一个ApiSelectorBuilder实例，用来控制接口被Swagger做成文档
                .select()
                // 用于指定扫描哪个包下的接口
                .apis(RequestHandlerSelectors.basePackage("com.example.knife4jtest"))
                // 选择所有的API，如果你只想为部分API生成文档，可以配置这里
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /**
     * 定义api文档主页面的基本信息
     * 访问地址：http://项目实际地址/doc.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("knife4j test")
                .description("API描述")
                // 版本号
                .version("3.0")
                .build();
    }

} 

3. 创建User实体类

@ApiModel: 用来标注实体类，常用配置项：

• value: model的别名，默认为类名
• description: model的详细描述

@ApiModelProperty: 用来标注实体类的字段，常用配置项：

• value: 字段说明
• example: 字段的示例值
• required: 是否为必填项

@Data
@ApiModel(description = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户id", required = true)
    private Integer id;

    @ApiModelProperty(value = "用户名", required = true)
    private String name;

}

4. 创建测试类和方法

@Api: 用在类上，该注解将一个Controller（Class）标注为一个Swagger资源（API），常用配置项：

• tags: API分组标签，具有相同标签的API将会被归并在一组内展示
• value: 如果tags没有定义，value将作为Api的tags使用

@ApiOperation: 用来描述接口，常用配置项：

• value: 接口的简单说明
• notes: 接口的详细说明

@ApiParam: 接口参数的说明，常用配置项：

• required: 是否必填，默认为false
• value: 参数说明

@RestController
@RequestMapping("user")
@Api(tags = "用户管理")
public class UserController {

    @GetMapping("get")
    @ApiOperation(value = "获取用户信息")
    public User get(@ApiParam(value = "用户id", required = true) @RequestParam Integer id) {
        User user = new User();
        user.setId(id);
        user.setName("张三");
        return user;
    }

}

5. 访问host+doc.html

点开用户管理的接口获取用户信息，查看更详细的接口文档：

Knife4j的增强功能

Knife4j的增强功能非常多，这里只列几个我非常喜欢并且常用的功能，对其他增强功能感兴趣的读者可以查看官方文档。

1. 开启增强功能

要使用Knife4j的增强功能，必须开启knife4j.enable=true，包括后面所讲解到的所有增强功能，都需要设置这个参数，此参数默认值为false

2. 开启生产环境保护策略

生产环境需要关闭文档时，可以设置这个参数knife4j.production=true，设置后访问文档会提示“Knife4j文档请求异常”，此参数默认值为false

3. 设置账号密码

knife4j.basic.enable=true

knife4j.basic.username=knife4jtest

knife4j.basic.password=test

设置后，访问文档时，需要输入账号密码，knife4j.basic.enable默认false

4. 过滤请求参数

我们在开发过程中经常会遇到这样一个问题，新增和修改接口时，修改接口需要传一个记录id，但是新增的接口不需要，新增和修改接口使用同一个Model时，前端同学看到新增接口中的id，会感到很困惑，我们可以通过在方法上使用自定义增强注解ApiOperationSupport中的ignoreParameters属性来解决这个问题

@PostMapping("add")
@ApiOperation(value = "新增用户")
@ApiOperationSupport(ignoreParameters = {"id"})
public Integer add(@ApiParam(value = "新增的用户", required = true) @RequestBody User user) {
    return 1;
}

@PostMapping("edit")
@ApiOperation(value = "编辑用户")
public Boolean edit(@ApiParam(value = "编辑的用户", required = true) @RequestBody User user) {
    return true;
}

新增用户的方法中使用了ApiOperationSupport注解的ignoreParameters属性后，请求参数中不会再展示id，新增和修改接口文档展示如下：

若您想了解更多内容，请关注公众号：图南随笔，vx：tunan66666

若您觉得还可以，请帮忙点个“赞”，谢谢～

关注我，查看更多技术干货文章