|
|
Controller 相关注解
@Api: 可设置对控制器的描述。
表 1. @Api 主要属性
|
注解属性
|
类型
|
描述
|
|
tags
|
String[]
|
控制器标签。
|
|
description
|
String
|
控制器描述（该字段被申明为过期）。
|
接口相关注解
|
注解属性
|
类型
|
描述
|
|
value
|
String
|
接口说明。
|
|
notes
|
String
|
接口发布说明。
|
|
tags
|
Stirng[]
|
标签。
|
|
response
|
Class<?>
|
接口返回类型。
|
|
httpMethod
|
String
|
接口请求方式。
|
|
注解属性
|
描述
|
|
paramType
|
查询参数类型，实际上就是参数放在那里。取值：
- path：以地址的形式提交数据，根据 id 查询用户的接口就是这种形式传参。
- query：Query string 的方式传参。
- header：以流的形式提交。
- form：以 Form 表单的形式提交。
|
|
dataType
|
参数的数据类型。取值：
|
|
name
|
参数名字。
|
|
value
|
参数意义的描述。
|
|
required
|
是否必填。取值：
|
Model 相关注解
|
注解属性
|
类型
|
描述
|
|
value
|
String
|
字段说明。
|
|
name
|
String
|
重写字段名称。
|
|
dataType
|
Stirng
|
重写字段类型。
|
|
required
|
boolean
|
是否必填。
|
|
example
|
Stirng
|
举例说明。
|
|
hidden
|
boolean
|
是否在文档中隐藏该字段。
|
|
allowEmptyValue
|
boolean
|
是否允许为空。
|
|
allowableValues
|
String
|
该字段允许的值，当我们 API 的某个参数为枚举类型时，使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。
|
- @ApiModel: 可设置接口相关实体的描述。
- @ApiModelProperty: 可设置实体属性的相关描述。
表 4. @ApiModelProperty 主要属性
- @ApiIgnore: Swagger 文档不会显示拥有该注解的接口。
- @ApiImplicitParams: 用于描述接口的非对象参数集。
- @ApiImplicitParam: 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用。
表 3. @ApiImplicitParam 主要属性
- @ApiOperation: 可设置对接口的描述。
表 2. @ApiOperation 主要属性
|
|
1、swagger2 注解整体说明
用于controller类上：
用于方法上面（说明参数的含义）：
|
注解
|
说明
|
|
@ApiOperation
|
方法的说明
|
|
@ApiImplicitParams、@ApiImplicitParam
|
方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明
|
用于方法上面（返回参数或对象的说明）：
|
注解
|
说明
|
|
@ApiResponses、@ApiResponse
|
方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明
|
对象类：
|
注解
|
说明
|
|
@ApiModel
|
用在JavaBean类上，说明JavaBean的 用途
|
|
@ApiModelProperty
|
用在JavaBean类的属性上面，说明此属性的的含议
|
2、@Api：请求类的说明
|
@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"
|
示例：
|
@Api(tags="订单模块")
@Controller
public class OrderController {
}
|
@Api 其它属性配置：
|
属性名称
|
备注
|
|
value
|
url的路径值
|
|
tags
|
如果设置这个值、value的值会被覆盖
|
|
description
|
对api资源的描述
|
|
basePath
|
基本路径
|
|
position
|
如果配置多个Api 想改变显示的顺序位置
|
|
produces
|
如, “application/json, application/xml”
|
|
consumes
|
如, “application/json, application/xml”
|
|
protocols
|
协议类型，如: http, https, ws, wss.
|
|
authorizations
|
高级特性认证时配置
|
|
hidden
|
配置为true ，将在文档中隐藏
|
3、@ApiOperation：方法的说明
|
@ApiOperation："用在请求的方法上，说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
|
3.1、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
|
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的说明、描述
required：参数是否必须必填
paramType：参数放在哪个地方
· query --> 请求参数的获取：@RequestParam
· header --> 请求参数的获取：@RequestHeader
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
|
示列：
|
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
}
|
4、@ApiResponses、@ApiResponse：方法返回值的状态码说明
|
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
|
示例：
|
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
...
return JsonResult.ok().put("page", pageUtil);
}
}
|
5、@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述
@ApiModel的用途有2个：
- 当请求数据描述，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
- 当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述。
5.1、当请求数据描述时， @RequestBody 时的使用
|
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名",required=true)
private String username;
@ApiModelProperty(value = "密码",required=true)
private String password;
// getter/setter省略
}
|
|
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value = "用户登录", notes = "")
@PostMapping(value = "/login")
public R login(@RequestBody UserLoginVO userLoginVO) {
User user=userSerivce.login(userLoginVO);
return R.okData(user);
}
}
|
5.2、@ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义
示例:
|
@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{
@ApiModelProperty(value = "是否成功",required=true)
private boolean success=true;
@ApiModelProperty(value = "错误码")
private Integer errCode;
@ApiModelProperty(value = "提示信息")
private String message;
@ApiModelProperty(value = "数据")
private Object data;
/* getter/setter 略*/
}
|
|