swagger扩展注解

@KPApiJsonlParam

• 作用：对入参是json的(@RequestBody)生成接口参数说明
  用法及效果

  示例一

  @ApiOperation(value = "设置用户", notes = "权限 auth:role:add:user")
  @KPApiJsonlParam({
      @ApiModelProperty(name = "roleId", value = "角色Id", required = true),
      @ApiModelProperty(name = "userIds", value = "用户id集合", required = true, dataType = "list")
  })
  @PostMapping(value = "/add/user")
  @ResponseBody
  public KPResult roleAddUser(@RequestBody RoleUserPO roleUserPO) {
      userRoleService.userRoleService(parameter);
      return KPResult.success();
  }
  

  

  示例二

  @ApiOperation(value = "批量注销", notes = "权限 auth:user:batch:cancel")
  @PostMapping(value = "/batch/cancel")
  @KPApiJsonlParam({
          @ApiModelProperty(name = "ids", value = "用户Id", required = true, dataType = "list")
  })
  @ResponseBody
  public KPResult doCancel(@RequestBody List<String> ids) {
      return userService.doCancel(ids);
  }
  

  

@KPApiJsonlParamMode

• 作用：对入参是json的(@RequestBody)生成接口参数说明，从现有的实体类上抽取指定的字段 或 屏蔽指定的字段

• 参数说明：

  separator：分隔符 默认是英文逗号

  component：目标实体类

  ignores：忽略的字段

  includes：包含的字段

  用法及效果

  示例一

    //展示UserListParamPO实体里面除去pageNum,pageSize的所有字段
    @ApiOperation(value = "查询用户信息-不带分页", notes = "权限 auth:user:page:list")
    @PostMapping(value = "/list")
    @KPApiJsonlParamMode(component = UserListParamPO.class, ignores = "pageNum,pageSize")
    @ResponseBody
    public KPResult<List<UserListCustomerPO>> queryList(@RequestBody UserListParamPO userListParamPO) {
        return KPResult.success(userService.queryList(userListParamPO));
    }
  
  

  

  示例二

  //展示DeptListParamPO实体里面isTree字段
  @ApiOperation(value = "查询部门下拉框")
  @PostMapping("/dept/select")
  @KPApiJsonlParamMode(component = DeptListParamPO.class, includes = "isTree")
  @ResponseBody
  public KPResult<List<DictionaryChildrenBO>> queryProjectSelect(@RequestBody DeptListParamPO deptListParamPO) {
      return KPResult.success(KPServiceUtil.getBean(DeptService.class).queryDeptSelect(deptListParamPO));
  }
  

  

权限注解

@PreAuthorize

• 作用：spring security 权限注解，用于在接口调用之前对用户权限进行验证。昆鹏框架进行二次发开 用于验证权限

• 参数说明：

  hasPermission：设置访问权限 第一个参数表示接口全路径，第二个参数表示权限标识

• 补充：权限控制具体操作，请查看 权限配置

  用法

  #表示调用该接口， 用户必须有auth:user:save 权限 权限控制具体查看 权限配置说明
    @PreAuthorize("hasPermission('/auth/user/save','auth:user:save')")
    @ApiOperation(value = "新增用户信息", notes="权限 auth:user:save")
    @PostMapping("/save")
    @KPVerifyNote
    @KPApiJsonlParamMode(component = UserEditParamPO.class, ignores = "userId")
    public KPResult<UserPO> save(@RequestBody UserEditParamPO userEditParamPO){
        userService.saveUser(userEditParamPO);
        return KPResult.success();
    }
  

@KPDataPermissions

• 作用：用于验证数据权限。数据权限控制在鉴权系统进行

• 参数说明：

  userFileName：用户id字段 默认 create_user_id

  deptFileName：默认id字段 默认 dept_id

  excludeTableName：要排除的表名, 多个表用逗号分隔 (如果我们的接口执行多个查询语句，但有的查询语句不需要再where 自动拼接数据权限)

• 补充：添加该注解后，查询的sql语句会自动根据当前用户角色设置的数据权限进行过滤（在最终查询语句中 自动拼接where条件 无需程序员添加数据权限过滤条件）、如果用户有多个角色、取最大数据权限进行查询

  用法以配置方式

    @PreAuthorize("hasPermission('/auth/post/page/list', 'auth:post:page:list')")
    @ApiOperation(value = "查询岗位信息分页列表", notes = "权限 auth:post:page:list")
    @PostMapping("/page/list")
    @KPDataPermissions(excludeTableName="auth_user")
    @KPVerifyNote
    public KPResult<PostPO> queryList(@RequestBody PostListParamPO postListParamPO){
        return KPResult.list(postService.queryPageList(postListParamPO));
    }
  

  数据权限设置方式 在角色列表中数据权限配置页面进行配置

校验器注解

@KPVerifyNote

• 作用：开启注解校验
• 说明：昆鹏框架开发了自己的注解校验器、简化用户对应参数的校验。如果使用注解校验器 需要先在接口上使用@KPVerifyNote 打开注解校验器 如果不加该注解 即使使用了注解校验 也不起作用
• 补充：注解校验器底层实现是 昆鹏工具类中 KPVerifyUtil 校验方法 KPVerifyUtil 提供全量的校验方法 单注解目前只提供以下注解 其他的会在后续新增
  用法

    @PreAuthorize("hasPermission('/auth/post/save','auth:post:save')")
    @ApiOperation(value = "新增岗位信息", notes="权限 auth:post:save")
    @PostMapping("/save")
    @KPVerifyNote
    @KPApiJsonlParamMode(component = PostEditParamPO.class, ignores = "postId")
    public KPResult<PostPO> save(@RequestBody PostEditParamPO postEditParamPO){
        postService.savePost(postEditParamPO);
        return KPResult.success();
    }
  

@KPNotNull

• 作用：非空校验

• 说明：加在实体类上用于校验非空 不限数据类型 任何类型都可进行校验

• 参数说明：

  errMeg：校验失败提示语

  用法

  @Data
  @Accessors(chain = true)
  @ApiModel(value = "PostEditParamPO对象", description = "岗位信息编辑入参")
  public class PostEditParamPO {
  
      private static final long serialVersionUID = 1L;
  
      @ApiModelProperty(value = "岗位Id", example = "岗位Id", required = true)
      @TableId(value = "post_id", type = IdType.ASSIGN_UUID)
      @KPNotNull(errMeg = "请输入岗位Id")
      @KPMaxLength(max = 36, errMeg = "岗位Id不能超过36个字符")
      private String postId;
  
      @ApiModelProperty(value = "岗位编码", example = "岗位编码", required = true)
      @TableField("post_code")
      @KPNotNull(errMeg = "请输入岗位编码")
      @KPLength(min = 2, max = 64, errMeg = "岗位编码须2~64个字符")
      private String postCode;
  
      @ApiModelProperty(value = "岗位名称", example = "岗位名称", required = true)
      @TableField("post_name")
      @KPNotNull(errMeg = "请输入岗位名称")
      @KPLength(min = 2, max = 64, errMeg = "岗位名称须2~64个字符")
      private String postName;
  }
  

@KPMaxLength

• 作用：最大长度校验

• 说明：加在实体类上用于字段最大长度校验 不限数据类型 任何类型都可进行校验

• 参数说明：

  errMeg：校验失败提示语

  max：最大长度 如果是字符串 表示长度 如果是数字 表示 最大数

  用法

  @Data
  @Accessors(chain = true)
  @ApiModel(value = "PostEditParamPO对象", description = "岗位信息编辑入参")
  public class PostEditParamPO {
  
      private static final long serialVersionUID = 1L;
  
      @ApiModelProperty(value = "岗位Id", example = "岗位Id", required = true)
      @TableId(value = "post_id", type = IdType.ASSIGN_UUID)
      @KPNotNull(errMeg = "请输入岗位Id")
      @KPMaxLength(max = 36, errMeg = "岗位Id不能超过36个字符")
      private String postId;
  
      @ApiModelProperty(value = "岗位编码", example = "岗位编码", required = true)
      @TableField("post_code")
      @KPNotNull(errMeg = "请输入岗位编码")
      @KPLength(min = 2, max = 64, errMeg = "岗位编码须2~64个字符")
      private String postCode;
  
      @ApiModelProperty(value = "岗位名称", example = "岗位名称", required = true)
      @TableField("post_name")
      @KPNotNull(errMeg = "请输入岗位名称")
      @KPLength(min = 2, max = 64, errMeg = "岗位名称须2~64个字符")
      private String postName;
  }
  

@KPLength

• 作用：长度校验

• 说明：加在实体类上用于长度校验 不限数据类型 任何类型都可进行校验

• 参数说明：

  errMeg：校验失败提示语

  min：最小值 如果是字符串 表示长度 如果是数字 表示 最小数

  max：最大值 如果是字符串 表示长度 如果是数字 表示 最大数

  用法

  @Data
  @Accessors(chain = true)
  @ApiModel(value = "PostEditParamPO对象", description = "岗位信息编辑入参")
  public class PostEditParamPO {
  
      private static final long serialVersionUID = 1L;
  
      @ApiModelProperty(value = "岗位Id", example = "岗位Id", required = true)
      @TableId(value = "post_id", type = IdType.ASSIGN_UUID)
      @KPNotNull(errMeg = "请输入岗位Id")
      @KPMaxLength(max = 36, errMeg = "岗位Id不能超过36个字符")
      private String postId;
  
      @ApiModelProperty(value = "岗位编码", example = "岗位编码", required = true)
      @TableField("post_code")
      @KPNotNull(errMeg = "请输入岗位编码")
      @KPLength(min = 2, max = 64, errMeg = "岗位编码须2~64个字符")
      private String postCode;
  
      @ApiModelProperty(value = "岗位名称", example = "岗位名称", required = true)
      @TableField("post_name")
      @KPNotNull(errMeg = "请输入岗位名称")
      @KPLength(min = 2, max = 64, errMeg = "岗位名称须2~64个字符")
      private String postName;
  }
  

其他注解

@KPExcludeInterfaceJournal

• 作用：排除记录接口日志

• 说明：昆鹏框架会记录所有接口调用日志, 如果某些接口不想记录 可以加入该接口进行屏蔽记录

  用法

    @ApiOperation(value = "查询首页用户登录数")
    @KPExcludeInterfaceJournal
    @PostMapping("/login/number")
    public KPResult<List<LoginNumberCustomerPO>> queryLoginNumber(@RequestBody List<String> projectCodes){
        return KPResult.success(welcomeService.queryLoginNumber(projectCodes));
    }
  

  如果不加入 @KPExcludeInterfaceJournal 注解 就会记录调用日志、可以在以下页面进行查询调用记录

@KPRepeatSubmitNote

• 作用：防抖注解，用于防止重复提交

• 说明：添加该注解后可以防止用户（同一个用户）重复提交

• 参数说明：

  value：间隔时间 单位毫秒 默认是800毫秒 表示用户在800毫秒内只能点击一次

  用法

    @PostMapping("/login")
    @ApiOperation(value = "普通登录")
    @KPApiJsonlParam({
        @ApiModelProperty(name = "userName", value = "用户账号", required = true, example = "admin1"),
        @ApiModelProperty(name = "password", value = "密码", required = true, example = "admin1admin1"),
        @ApiModelProperty(name = "projectCode", value = "项目编号", required = true, example = "authentication"),
    })
    @KPRepeatSubmitNote(1000) # 表示同一用户在1秒内只能点击一次，如果不设置1000 则默认是800毫秒
    public KPResult<UserLoginCustomerPO> login(@RequestBody JSONObject parameter) {
        return KPResult.success(loginService.login(parameter));
    }
  

  

@KPProhibitCrawlerNote

• 作用：禁止爬虫，用于防止关键接口数据被爬虫抓取

• 说明：添加该注解后 可以有效保护关键接口数据被爬虫抓取

• 参数说明：

  minute：间隔时间 单位分 默认是5分

  minuteCount：接口调用次数 默认50次

  forbidHouse：禁止访问时间 单位小时 默认12小时

  blacklist：禁止访问次数 默认3次

• 补充：如果接口添加该注解@KPProhibitCrawlerNote 不设置任何参数 表示 用户5分钟内最多访问该接口50次 如果5分钟超过50次 加入临时黑名单 12小时内禁止访问 同时临时黑名单次数+1。 当用户临时黑名单次数超过3次 则加入永久黑名单 禁止访问。 加入永久黑名单后 相当于该用户永远无法再获取该接口数据

  用法

    @PreAuthorize("hasPermission('/auth/user/page/list', 'auth:user:page:list')")
    @ApiOperation(value = "查询用户信息分页列表", notes = "权限 auth:user:page:list")
    @PostMapping("/page/list")
    @KPVerifyNote
    @KPProhibitCrawlerNote(minute = 10, minuteCount = 70)
    public KPResult<UserListCustomerPO> queryPageList(@RequestBody UserListParamPO userListParamPO){
        return KPResult.list(userService.queryPageList(userListParamPO));
    }
  

@KPObjectChangeLogNote

• 作用：数据库表字段修改记录

• 说明：添加该注解后 可以记录指定表里面所有字段变更记录 无需开发人员手动记录变化、 例如用户记录 用户名 从 admin 变为 adm，性别男 变为 女

• 参数说明：

  parentMapper：查询数据库所调用的mapper类

  identification：唯一标识(数据库主键)，查询数据库的条件， 如果数据库字段和实体表字段名称不一样 写 字段名称|数据库字段名称 如 houseId,house_id 英文逗号

  operateType：操作类型 填充ObjectChangeLogOperateType 如 ObjectChangeLogOperateType.ADD

  businessType：业务类型， 使用者自己扩展

  saveDS：保存日志的数据源 默认 kunpeng_auth

  saveTableName：保存日志的数据库表名 默认 auth_object_change_log

  notRecordField：不记录的改变字段 默认 createDate,updateDate,deleteFlag

• 补充：添加注解后 会自动记录指定数据表中字段改变内容、开发人员无需开发、只想要前端展示一个变化轨迹页面即可

  用法

    @PreAuthorize("hasPermission('/auth/role/save','auth:role:save')")
    @ApiOperation(value = "新增角色信息", notes = "权限 auth:role:save")
    @PostMapping("/save")
    @KPVerifyNote
    @KPObjectChangeLogNote(parentMapper = RoleMapper.class, identification = "roleId,role_id", operateType = ObjectChangeLogOperateType.ADD, businessType="角色")
    @KPApiJsonlParamMode(component = RoleEditParamPO.class, ignores = "roleId")
    public KPResult<RolePO> save(@RequestBody RoleEditParamPO roleEditParamPO) {
        roleService.saveRole(roleEditParamPO);
        return KPResult.success();
    }
  
    @PreAuthorize("hasPermission('/auth/role/update','auth:role:update')")
    @ApiOperation(value = "修改角色信息", notes = "权限 auth:role:update")
    @PostMapping("/update")
    @KPObjectChangeLogNote(parentMapper = RoleMapper.class, identification = "roleId,role_id", operateType = ObjectChangeLogOperateType.UPDATE, businessType="角色")
    @KPVerifyNote
    public KPResult<RolePO> update(@RequestBody RoleEditParamPO roleEditParamPO) {
        roleService.updateRole(roleEditParamPO);
        return KPResult.success();
    }
  

  

@KPObjectChangeLogListNote

• 作用：多张数据库表修改记录 @KPObjectChangeLogNote注解的集合

• 说明：如果一个接口里面要记录多张表的修改记录，可以使用该注解

  用法

  示例一

    @PreAuthorize("hasPermission('/auth/user/save','auth:user:save')")
    @ApiOperation(value = "新增用户信息", notes="权限 auth:user:save")
    @PostMapping("/save")
    @KPVerifyNote
    @KPObjectChangeLogListNote({
        @KPObjectChangeLogNote(parentMapper = UserMapper.class, identification = "userId,userId", operateType = ObjectChangeLogOperateType.ADD, businessType="用户"),
        @KPObjectChangeLogNote(parentMapper = UserRoleMapper.class, identification = "aurId,aur_id", operateType = ObjectChangeLogOperateType.ADD, businessType="用户角色")
    })
    @KPApiJsonlParamMode(component = UserEditParamPO.class, ignores = "userId")
    public KPResult<UserPO> save(@RequestBody UserEditParamPO userEditParamPO){
        userService.saveUser(userEditParamPO);
        return KPResult.success();
    }
  

  示例二

    @PreAuthorize("hasPermission('/auth/user/save','auth:user:save')")
    @ApiOperation(value = "新增用户信息", notes="权限 auth:user:save")
    @PostMapping("/save")
    @KPVerifyNote
    @KPObjectChangeLogNote(parentMapper = UserMapper.class, identification = "userId,userId", operateType = ObjectChangeLogOperateType.ADD, businessType="用户")
    @KPObjectChangeLogNote(parentMapper = UserRoleMapper.class, identification = "aurId,aur_id", operateType = ObjectChangeLogOperateType.ADD, businessType="用户角色")
    @KPApiJsonlParamMode(component = UserEditParamPO.class, ignores = "userId")
    public KPResult<UserPO> save(@RequestBody UserEditParamPO userEditParamPO){
        userService.saveUser(userEditParamPO);
        return KPResult.success();
    }