springboot+knife4j初体验

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案，帮助开发者快速聚合使用OpenAPI规范。

knife4j是一个很好的接口文档工具，前身是swagger-bootstrap-ui。早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字Knife4j，适用于单体和微服务项目。
使用knife4j是为了简化内部对接，便于测试和前端调试，以便简化程序猿编写接口文档，在本地环境和测试环境可以使用，考虑到安全问题不要暴露在生产环境。
实例
1、pom依赖
使用knife4j2.0.6及以上版本，springboot的版本必须在2.2.x以上

	
        org.springframework.boot
        spring-boot-starter-parent
        2.7.2
         
    
    
        
            org.springframework.boot
            spring-boot-starter-web
        
        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            2.0.9
        
    
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

2、knife4j配置类

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "docket")
    public Docket docket() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("")
                        //描述字段支持Markdown语法
                        .description("Knife4j RESTful APIs")
                        .contact(new Contact("caocao","https://doc.xiaominfo.com/","xiaoymin@foxmail.com"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("用户服务")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.*.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

3、测试controller

@Api(tags = "用户模块")
@RestController
@RequestMapping("/index")
public class IndexController {

    @ApiOperation(value = "向客人问好")
    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @GetMapping("/sayHi")
    public ResponseEntity sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }

    @ApiOperation("添加")
    @PostMapping("/add")
    public UserVO add(@RequestBody UserAddRequest userAddRequest) {
        // 将数据写到数据库
        UserVO userVO = new UserVO();
        BeanUtils.copyProperties(userAddRequest, userVO);
        userVO.setId(1L);
        userVO.setCreateTime(LocalDateTime.now());
        userVO.setUpdateTime(LocalDateTime.now());
        return userVO;
    }

    @ApiOperation("修改")
    @PostMapping("/edit")
    public UserVO edit(@RequestBody UserEditRequest userEditRequest) {
        // 修改数据库的数据
        UserVO userVO = new UserVO();
        BeanUtils.copyProperties(userEditRequest, userVO);
        userVO.setUpdateTime(LocalDateTime.now());
        return userVO;
    }

    @ApiOperation("查找")
    @GetMapping("/find")
    public List find(UserQueryRequest userQueryRequest) {
        UserVO userVO = new UserVO();
        BeanUtils.copyProperties(userQueryRequest, userVO);
        userVO.setUpdateTime(LocalDateTime.now());
        List list = new ArrayList<>();
        list.add(userVO);
        return list;
    }

    @ApiOperation("删除")
    @PostMapping("/delete")
    public void delete(Long id) {
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

4、测试实体

@Data
@ApiModel("添加用户")
public class UserAddRequest {
    @ApiModelProperty(value = "用户名", required = true)
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;
}
@Data
@ApiModel("修改用户")
public class UserEditRequest {
    @ApiModelProperty(value = "用户ID", required = true)
    private Long id;

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

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;
}
@Data
@ApiModel(value = "查询用户", description = "用户description")
public class UserQueryRequest {

    @ApiModelProperty("用户id")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty("创建时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @ApiModelProperty("修改时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updateTime;
}
@Data
@ApiModel(value = "用户实体", description = "用户description")
public class UserVO {

    @ApiModelProperty("用户id")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty(value = "创建时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @ApiModelProperty(value = "修改时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updateTime;

    @ApiModelProperty("删除标记。0：未删除 其他：已删除")
    private Long deletedFlag;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

5、配置application.properties

spring.mvc.pathmatch.matching-strategy=ant_path_matcher
1

若不配置，则报错：Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
6、测试
启动服务即可，访问地址为http://localhost:8080/doc.html

通过可视化页面可以查看接口文档，如下

接口调试，如下

接口文档导出

尝试在实际工程中应用解决问题，提高效率，加油吧，少年。