美文网首页菜鸟要飞
项目工程接口规范(swagger、参数validation、权限

项目工程接口规范(swagger、参数validation、权限

作者: 万总有点菜 | 来源:发表于2021-08-17 13:20 被阅读0次

    Swagger注解说明

    接口注解

    @Api:用在类上,说明该类的作用。
    @ApiOperation:注解来给API增加方法说明。
    @ApiImplicitParams : 用在方法上包含一组参数说明。
    @ApiImplicitParam:用来注解来给方法入参增加说明。

    返回类注解

    @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    @ApiModelProperty:描述一个model的属性

    接口注解说明(必须配置)

    样例1

    @ApiOperation(value = "国密加密", notes = "获取系统国密加密,用于登录接口测试") 
    @RequestMapping(value = "/encrypt", method = RequestMethod.POST)
    @ApiImplicitParams({
           @ApiImplicitParam(name = "Request-DateTime", value = "发起请求时间", paramType = "header", dataType = "date", required = true, defaultValue = "2019-08-17 06:30:52"),
           @ApiImplicitParam(name = "content", value = "内容", paramType = "query", dataType = "string", required = true)
        })
        public CommonResult encrypt(String content) {
            CommonResult result = new CommonResult().init();
            try {
                result.success("ciphertext", CryptoUtils.encryptBcdBySystem(content));
    
            } catch (DecoderException e) {
                e.printStackTrace();
                result.fail(MsgCodeUtils.MSG_CODE_UNKNOWN);
            }
    
            return (CommonResult) result.end();
        }
    

    样例2

    @ApiOperation(value = "删除字典", notes = "Request-DateTime样例:2018-09-29 11:26:20")
    @ApiImplicitParams({
                @ApiImplicitParam(name = "Access-Token", value = "访问token", paramType = "header", dataType = "string", required = true),
                @ApiImplicitParam(name = "Request-DateTime", value = "发起请求时间", paramType = "header", dataType = "date", required = true),
                @ApiImplicitParam(name = "id", value = "字典id", paramType = "path", dataType = "string", required = true)
                //paramType 有五个可选值 : path 请求参数的获取:@PathVariable, query 请求参数的获取:@RequestParam, body, header 请求参数的获取:@RequestHeader, form
        })
        @RequestMapping(value = "{id}", method = RequestMethod.DELETE)
        public CommonResult delete(@PathVariable String id) {
            CommonResult result = new CommonResult().init();
            if (StringUtils.isBlank(id)) {
                return (CommonResult) result.fail(MsgCodeUtils.MSG_CODE_ID_IS_NULL).end();
            }
            if (0 < dictionaryService.delete(new Dictionary(id))) {
                result.success();
                logger.info("删除字典:{}成功!", id);
            } else {
                result.fail(MsgCodeUtils.MSG_CODE_UNKNOWN);
                logger.info("删除字典:{}失败!", id);
            }
            return (CommonResult) result.end();
        }
    

    接口信息配置

    @RequestMapping(value = "/encrypt", method = RequestMethod.POST)
    配置接口地址,以及接口的请求方式
    @ApiOperation(value = "国密加密", notes = "获取系统国密加密,用于登录接口测试")
    value填写接口中文标题,notes填写接口的功能说明
    @ApiImplicitParam(name = "Request-DateTime", value = "发起请求时间", paramType = "header", dataType = "date", required = true, defaultValue = "2019-08-17 06:30:52")
    name,参数的英文名称;value,参数的中文名称,paramType,参数的位置;dataType,参数类型(paramType 有五个可选值 : path 请求参数的获取:@PathVariable, query 请求参数的获取:@RequestParam, body, header 请求参数的获取:@RequestHeader, form不常用);required,参数是否必填;defaultValue,参数样例数据。

    以上配置信息,接口都是必填

    接口参数配置(有实体类的,必须配置)

    @ApiOperation(value = "创建区域", notes = "Request-DateTime样例:2018-09-29 11:26:20")
    @ApiImplicitParams({
                @ApiImplicitParam(name = "Access-Token", value = "访问token", paramType = "header", dataType = "string", required = true),
                @ApiImplicitParam(name = "Request-DateTime", value = "发起请求时间", paramType = "header", dataType = "date", required = true)
        })
    @RequestMapping(value = "", method = RequestMethod.POST)
    public CommonResult create(@Validated(Create.class) @RequestBody @ApiParam(value = "区域vo") AreaVO vo, BindingResult bindingResult) {
            CommonResult result = new CommonResult().init();
            //参数验证
            if (bindingResult.hasErrors()) {
                return (CommonResult) result.failIllegalArgument(bindingResult.getFieldErrors()).end();
            }
            if (null != areaService.getByName(vo.getName())) {
                return (CommonResult) result.failCustom(MsgCodeUtils.MSG_CODE_DATA_EXIST, "区域名称=" + vo.getName()).end();
            }
            Area parentArea = areaService.get(vo.getParentId());
            if (null == parentArea) {
                //父级节点不存在
                result.fail(MsgCodeUtils.MSG_CODE_PARENT_NODE_NOT_EXIST);
                return (CommonResult) result.end();
            }
            Area area = new Area();
            BeanCustomUtils.copyProperties(vo, area);
            area.setParent(parentArea);
            if (0 < areaService.save(area)) {
                result.success("area", area);
                logger.info("创建区域:{}成功!", vo.getName());
    
            } else {
                result.fail(MsgCodeUtils.MSG_CODE_UNKNOWN);
                logger.info("创建区域:{}失败!", vo.getName());
            }
            return (CommonResult) result.end();
        }
    

    @Validated(Create.class) @RequestBody @ApiParam(value = "区域vo") AreaVO vo, BindingResult bindingResult
    @Validated(Create.class),参数校验,“Create.class”表示具体的分组,详见vo类样例里面参数的配置(@NotBlank(groups = Create.class, message = "父级区域ID不能为空"));
    @ApiParam(value = "区域vo") AreaVO vo,参数的名称说明配置;
    BindingResult bindingResult,这个必须填写与接口内部的代码配套

    CommonResult result = new CommonResult().init();
    //参数验证
    if (bindingResult.hasErrors()) {
         return (CommonResult) result.failIllegalArgument(bindingResult.getFieldErrors()).end();
    }
    

    具体vo类样例

    package com.lczyfz.edp.springboot.core.vo;
    
    import com.lczyfz.edp.springboot.core.entity.BaseVO;
    import com.lczyfz.edp.springboot.core.validation.Create;
    import com.lczyfz.edp.springboot.core.validation.Update;
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import reactor.util.annotation.Nullable;
    
    import javax.validation.constraints.NotBlank;
    import javax.validation.constraints.NotEmpty;
    import javax.validation.constraints.Pattern;
    import java.util.Date;
    
    /**
     * Created by maple on 2018-10-11.
     */
    @ApiModel(value = "AreaVO", description = "AreaVO")
    public class AreaVO extends BaseVO {
    
        @NotBlank(groups = Create.class, message = "父级区域ID不能为空")
        @ApiModelProperty(value = "父级区域ID", example = "1")
        private String parentId;    // 父级菜单
        //    @ApiModelProperty(value = "所有父级编号", example = "0,1,2,3,10,")
    //    private String parentIds; // 所有父级编号
        @NotBlank(groups = Create.class, message = "区域名称名称不能为空")
        @ApiModelProperty(value = "名称", example = "区域管理")
        private String name;    // 名称
        @ApiModelProperty(value = "排序", example = "50")
        private Long sort;    // 排序
    
    
        @ApiModelProperty(value = "区域编码", example = "350501")
        @Pattern(regexp = "[1-9]\\d{5}(?!\\d)",
                message = "区域编码错误", groups = {Create.class, Update.class})
        private String code;    // 区域编码
        @ApiModelProperty(value = "区域类型", example = "1")
        private String type;    // 区域类型(1:国家;2:省份、直辖市;3:地市;4:区县)
    
    
        public AreaVO() {
        }
        public String getParentId() {
            return parentId;
        }
        public void setParentId(String parentId) {
            this.parentId = parentId;
        }
        public String getName() {
            return name;
        }
        public void setName(String name) {
            this.name = name;
        }
        public Long getSort() {
            return sort;
        }
        public void setSort(Long sort) {
            this.sort = sort;
        }
        public String getCode() {
            return code;
        }
        public void setCode(String code) {
            this.code = code;
        }
        public String getType() {
            return type;
        }
        public void setType(String type) {
            this.type = type;
        }
        @Override
        public String toString() {
            return "AreaVO{" +
                    "parentId='" + parentId + '\'' +
                    ", remarks='" + remarks + '\'' +
                    ", name='" + name + '\'' +
                    ", sort=" + sort +
                    ", code='" + code + '\'' +
                    ", type='" + type + '\'' +
                    '}';
        }
    }
    
    

    使用的是 javax.validation.constraints.* 的参数检验方法
    @NotBlank(groups = Create.class, message = "父级区域ID不能为空")
    @ApiModelProperty(value = "父级区域ID", example = "1")
    private String parentId; // 父级菜单
    @ApiModelProperty中的value为参数的中文名称,example为参数的数据样例,两个参数必填

    vo类,根据接口传参需要进行创建,不要有多余的属性

    接口结果返回类说明(返回实体的,必须配置)

    使用class EntityResult<T>作为接口结果返回

     @ApiOperation(value = "获取当前用户可查看的用户信息", notes = "获取当前用户可查看的用户信息表,getRequest-DateTime样例:2018-09-29 11:26:20")
      @RequestMapping(value = {"findCurrentUseRoleList"}, method = RequestMethod.GET)
    //    @RequiresRoles("dept")
    //    @RequiresPermissions("sys:user:view")
      @ApiImplicitParams({
                @ApiImplicitParam(name = "Access-Token", value = "访问token", paramType = "header", dataType = "string", required = true),
                @ApiImplicitParam(name = "Request-DateTime", value = "发起请求时间", paramType = "header", dataType = "date", required = true, defaultValue = "2019-08-17 06:30:52")
        })
        public EntityResult<User> findCurrentUseRoleList() {
            EntityResult<User> result = new EntityResult<User>().init();
            User user = UserUtils.getUser();
            List<User> userList = userService.findCurrentUseRoleList(new UserPageVO());
            List<User> userLists = new ArrayList<>();
            //过滤当前登入用户
            if (user != null) {
                for (User user1 : userList) {
                    if (!user1.getId().equals(user.getId())) {
                        userLists.add(user1);
                    }
                }
            }
    //        result.success("user", userLists);
            result.setData(userLists.get(0));
            return (EntityResult<User>) result.end();
        }
    
    样例

    接口权限配置(必须配置)

    @ApiOperation(value = "用户列表", notes = "根据条件获取用户列表,getRequest-DateTime样例:2018-09-29 11:26:20")
    @RequestMapping(value = {"", "list"}, method = RequestMethod.GET)
    @RequiresRoles("dept")
    @RequiresPermissions("sys:user:view")
    @ApiImplicitParams({
                @ApiImplicitParam(name = "Access-Token", value = "访问token", paramType = "header", dataType = "string", required = true),
                @ApiImplicitParam(name = "Request-DateTime", value = "发起请求时间", paramType = "header", dataType = "date", required = true, defaultValue = "2019-08-17 06:30:52")
        })
        public PageResult<User> userList(@Validated UserPageVO pageVO, BindingResult bindingResult) {
    
            PageResult<User> result = new PageResult<User>().init();
            //参数验证
            if (bindingResult.hasErrors()) {
                return (PageResult<User>) result.failIllegalArgument(bindingResult.getFieldErrors()).end();
            }
            Page<User> page = new Page<>(pageVO.getPageNo(), pageVO.getPageSize(), pageVO.getOrderBy());
            result.success(userService.findPage(page, pageVO, true));
            return (PageResult<User>) result.end();
        }
    

    @RequiresRoles("dept"),有当前角色的用户可访问;
    @RequiresPermissions("sys:user:view"),有当前权限标识的用户可访问;该权限标识在菜单配置上填写。


    权限标识配置

    接口分组配置(必须配置)

    在swagger的配置文件中,对接口进行分组配置

    @Bean
    public Docket createRestApiActiviti() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.lczyfz.edp.springboot"))//扫描的包路径
                    .paths(PathSelectors.ant("/api/activiti/**")) //接口url
                    .build()
                    .groupName("工作流引擎接口"); //分组中文名称
        }
    
    参考截图
    分组查询接口

    相关文章

      网友评论

        本文标题:项目工程接口规范(swagger、参数validation、权限

        本文链接:https://www.haomeiwen.com/subject/mggbbltx.html