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

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("工作流引擎接口"); //分组中文名称
    }
参考截图

分组查询接口
最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 206,126评论 6赞 481
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 88,254评论 2赞 382
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 152,445评论 0赞 341
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 55,185评论 1赞 278
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 64,178评论 5赞 371
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,970评论 1赞 284
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,276评论 3赞 399
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,927评论 0赞 259
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 43,400评论 1赞 300
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,883评论 2赞 323
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,997评论 1赞 333
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,646评论 4赞 322
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,213评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,204评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,423评论 1赞 260
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 45,423评论 2赞 352
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,722评论 2赞 345