Swagger注解介绍及常用参数配置与运用
1 @API
作用于类,放置于controller的一个类上,标志这个类是Swagger资源。资源影响Swagger的根文档、资源列表和该特定资源的API声明。swagger将只包含和声明使用@Api注释的类,而忽略其他资源(servlet等)
1.1 参数
参数名称 | 说明 | 类型 | 默认值 | 备注 |
---|---|---|---|---|
tags | 说明 | Sting | "" | 当tags为""或者未指定使用默认值时,显示为@API标注的类名,如UserInfoController显示为user-info-controller |
description | 描述 | String | "" | 当description为""或者未指定使用默认值时,显示为@API标注的类名,如UserInfoController显示为User Info Controller |
1.2 实例代码
@Api(
tags = "用户",
description = "User Info Controller"
)
@Controller
@RequestMapping("/user")
public class UserInfoController {
...
}
1.3 示例图
2 @ApiOperation
描述API方法,作用于方法上面,放置于标注为@API注解类的方法上,用户表示一个http的请求
2.1 参数
参数名称 | 说明 | 类型 | 默认值 | 备注 |
---|---|---|---|---|
value | 方法说明 | String | "" | 必填 |
httpMethod | 请求方法 | String | "" | |
produces | 输出类型 | String | "" | |
response | 返回类型 | Class<?> | java.lang.Void.class | |
notes | 方法描述详情 | String | "" |
2.2 实例代码
@ApiOperation(
value = "根据ID查找用户信息接口", httpMethod = "GET",
produces = "application/json",response = Dto.class,
notes = "根据ID查找用户信息"+
"<p>成功:success = ‘true’ | 失败:success = ‘false’ 并返回错误码,如下:</p>" +
"<p>错误码:</p>"+
"<p>10000 : 用户信息不存在 </p>"
)
@RequestMapping(value="/select/{id}",method = RequestMethod.GET)
@ResponseBody
public Dto<Object> selectUserinfoByid(@PathVariable("id") Integer id){
Userinfo userinfo = userinfoService.selectUserinfoById(id);
if(userinfo != null){
return DtoUtil.returnSuccess("查询用户信息成功");
}
return DtoUtil.returnFail("用户信息不存在","10000");
}
2.3 示例图
3 @ApiImplicitParams
多个参数描述,作用于标注@ApiOperation注解的方法上,解释请求参数里边添加@ApiImplicitParam()注解
3.1 参数
参数名称 | 说明 | 类型 | 默认值 | 备注 |
---|---|---|---|---|
name | 参数名称 | String | "" | 当name使用""后者未指定使用默认值时,显示为参数指定的参数名 |
value | 参数描述 | String | "" | 当value使用""后者未指定使用默认值时,显示为参数指定的参数名 |
paramType | 参数类型 | String | "" | 当paramType使用""后者未指定使用默认值时,根据参数的实际来源显示,如果来源于请求路径则显示为path |
require | 是否必需 | boolean | false |
3.2 实例代码
@ApiOperation(
value = "根据ID查找用户信息接口", httpMethod = "GET",
produces = "application/json",response = Dto.class,
notes = "根据ID查找用户信息"+
"<p>成功:success = ‘true’ | 失败:success = ‘false’ 并返回错误码,如下:</p>" +
"<p>错误码:</p>"+
"<p>10000 : 用户信息不存在 </p>"
)
@ApiImplicitParams(
@ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", required = true)
)
@RequestMapping(value="/select/{id}",method = RequestMethod.GET)
@ResponseBody
public Dto<Object> selectUserinfoByid(@PathVariable("id") Integer id){
Userinfo userinfo = userinfoService.selectUserinfoById(id);
if(userinfo != null){
return DtoUtil.returnSuccess("查询用户信息成功");
}
return DtoUtil.returnFail("用户信息不存在","10000");
}
3.3 示例图
4 @ApiParam
描述API方法,,作用于标注@ApiOperation注解的方法的参数上,用于参数字段的说明
4.1 参数
参数名称 | 说明 | 类型 | 默认值 | 备注 |
---|---|---|---|---|
name | 参数名称 | String | "" | 当name使用""后者未指定使用默认值时,显示为参数指定的参数名 |
value | 参数描述 | String | "" | 当value使用""后者未指定使用默认值时,显示为参数指定的参数名 |
required | 是否必需 | boolean | false |
4.2 实例代码
@ApiOperation(
value = "根据ID查找用户信息接口", httpMethod = "GET",
produces = "application/json",response = Dto.class,
notes = "根据ID查找用户信息"+
"<p>成功:success = ‘true’ | 失败:success = ‘false’ 并返回错误码,如下:</p>" +
"<p>错误码:</p>"+
"<p>10000 : 用户信息不存在 </p>"
)
@RequestMapping(value="/select/{id}",method = RequestMethod.GET)
@ResponseBody
public Dto<Object> selectUserinfoByid(@ApiParam(name = "id",value = "用户ID",required = true) @PathVariable("id") Integer id){
Userinfo userinfo = userinfoService.selectUserinfoById(id);
if(userinfo != null){
return DtoUtil.returnSuccess("查询用户信息成功");
}
return DtoUtil.returnFail("用户信息不存在","10000");
}
4.3 示例图
5 @ApiModel
作用于类,对类进行说明,用于实体类接收或者返回
5.1 参数
参数名称 | 说明 | 类型 | 默认值 | 备注 |
---|---|---|---|---|
value | 对象名 | String | "" | |
description | 对象描述 | String | "" |
5.2 实例代码
@ApiModel(value = "角色Model",description = "角色表实体对象")
public class Roleinfo {
@ApiModelProperty(
value = "角色ID",
name = "roleId",
dataType = "Integer",
required = true
)
private Integer roleId;
@ApiModelProperty(
value = "角色名称",
name = "roleName",
dataType = "String",
required = true
)
}
5.3 示例图
5 @ApiModelProperty
作用于实体类,用于实体类中某个字段,,用对象接收参数时,描述对象的一个字段
5.1 参数
参数名称 | 说明 | 类型 | 默认值 | 备注 |
---|---|---|---|---|
value | 参数解释 | String | "" | |
name | 参数名称 | String | "" | |
dataType | 属性类型 | String | "" | |
required | 是否必填 | boolean | false | |
example | 示例 | String | ||
hidden | 隐藏 | boolean | fasle |
5.2 实例代码
@Api(
tags = "用户",
description = "User Info Controller"
)
@Controller
@RequestMapping("/user")
public class UserInfoController {
@Autowired
private UserinfoService userinfoService;
@ApiOperation(
value = "新增用户信息接口", httpMethod = "POST",
produces = "application/json", response = Dto.class,
notes = "新增用户信息" +
"<p>成功:success = ‘true’ | 失败:success = ‘false’ 并返回错误码,如下:</p>" +
"<p>错误码:</p>" +
"<p>10001 : 添加用户信息失败 </p>"
)
@RequestMapping(value = "/insert", method = RequestMethod.POST)
@ResponseBody
public Dto<Object> insertUserinfo(Userinfo userinfo){
int row = userinfoService.insert(userinfo);
if(row > 0){
return DtoUtil.returnSuccess("添加用户信息成功");
}
return DtoUtil.returnFail("添加用户信息失败", "10002");
}
}
@ApiModel(value = "用户Model")
public class Userinfo {
@ApiModelProperty(
value = "用户id",
name = "id",
dataType = "Integer",
required = false
)
private Integer userId;
@ApiModelProperty(
value = "账号",
name = "userAccount",
dataType = "String",
required = true
)
private String userAccount;
@ApiModelProperty(
value = "密码",
name = "userPassword",
dataType = "String",
required = true
)
private String userPassword;
@ApiModelProperty(
value = "用户名",
name = "userName",
dataType = "String",
required = false
)
private String userName;
@ApiModelProperty(
value = "年龄",
name = "userAge",
dataType = "Integer"
)
private Integer userAge;
...
getter and setter
...
}
5.3 示例图
附件:测试源码
链接:https://pan.baidu.com/s/1N_wxYxJpX5rVF4drF69C_A
提取码:ew5d