公司项目JAVA开发规范总结（四）——knife4j使用规范

四、knife4j使用规范

概要：knife4j的集成，便于项目接口的调试，可根据代码注解生成接口文档，注解的编写也助于代码的理解和查阅。

1、与实体类相关的注解：

@ApiModel：对该类做出解释

@ApiModelProperty：对类中的属性进行解释

@ApiModel("响应实体")
public class PacketHttpRes_V32<T> {
	
    @ApiModelProperty(value = "结果码 200:成功 500:具体异常信息 400:参数异常 401:未授权的请求 403:无权访问")
	private Integer returnCode;
}
1
2
3
4
5
6

生成的文档：

2、与接口相关的注解：

@Api:用在Controller上，对其进行注释，其注释属性是tags

@ApiOperation：写在Controller的方法上，可进行接口命名注释和接口作用描述；其注释属性：value（命名）、notes（接口描述）

@ApiParam：可加在接口的参数上，不过单纯加它会出现类型Body的情况，需要配合@RequestParam，如下所示：

@ApiImplicitParam【推荐】：统一对接口中的参数进行注释，注释类型明确

大概如下：

@RestController
@RequestMapping("/TeachingPlan/ShareTpMgr")
@Validated
@Slf4j
@Api(tags = "教师端端共享教案库管理")
public class ShareTpMgrOfTeaController extends BaseController {
    
    @ApiImplicitParams({
        @ApiImplicitParam(name = "UserID", value = "用户ID", dataType = "string", paramType = "query",
                          required = true, defaultValue = "1") 
    })
    
	@ApiOperation(value = "获取共享教材信息列表(中小学)", notes = "获取可访问的教材信息列表以及历史访问信息")
	@RequestMapping(value = "/GetCanVisBookList", method = RequestMethod.GET)
    public PacketHttpRes_V32<?> GetCanVisBookList(
        @ApiParam("用户ID") @NotBlank(message = "--UserID不能为空--") String UserID,

        @ApiParam("是否查询自己共享的，0或不传查询全部，1为查询自己共享的，2为查询非自己共享的")
        @RequestParam(value = "IsQueryBySelf", required = false, defaultValue = "0")
        @NotNull(message = "--IsQueryBySelf不能为空--")
        @IntegerValidator(params = {0, 1, 2}, message = "--IsQueryBySelf参数错误--") 
        Integer IsQueryBySelf,
        HttpServletResponse response
    )
}
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

输出文档如图所示：

调试如图所示：

关于Knife4j的开关：

由applications.properties配置控制

#开启knife4j的增强模式
knife4j.enable=true
#是否为生产环境进行拒绝访问；ture为关闭knife4j页面访问功能
knife4j.production=false
#开启账户登录模式
knife4j.basic.enable=true
# Basic认证用户名
knife4j.basic.username=admin
# Basic认证密码
knife4j.basic.password=lg123456
1
2
3
4
5
6
7
8
9
10