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

Steady Ben

已于 2023-09-26 19:34:22 修改

阅读量3.4k

点赞数

分类专栏： # JAVA编码规范文章标签： java spring boot 前端

于 2022-06-21 19:18:39 首次发布

本文链接：https://blog.csdn.net/weixin_44593275/article/details/125396955

版权

JAVA编码规范专栏收录该内容

4 篇文章 2 订阅

订阅专栏

三、knife4j使用规范

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

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

@ApiModel：对该类做出解释

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

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

生成的文档：
在这里插入图片描述

2、与接口相关的注解：

@Api:用在Controller上，对其进行注释，其注释属性是tags
在这里插入图片描述

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

@ApiParam：可加在接口的参数上，不过单纯加它会出现类型Body的情况，需要配合@RequestParam，如下所示：
$[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-xvum2Ocx-1655810125190)(E:\AppData\Roaming\Typora\typora-user-images\image-20220616201537459.png)]$

@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
    )
}

输出文档如图所示：
在这里插入图片描述

调试如图所示：
在这里插入图片描述

关于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