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