菜鸟要飞

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

2021-08-17  本文已影响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("工作流引擎接口"); //分组中文名称
    }
参考截图
分组查询接口
上一篇下一篇

猜你喜欢

热点阅读