注解
@Api:
作用在类上,用来标注该类具体实现内容。表示标识这个类是swagger的资源 。
参数:
1. tags:可以使用tags()允许您为操作设置多个标签的属性,而不是使用该属性。
2. description:可描述描述该类作用。
@ApiImplicitParam:
作用在方法上,表示单独的请求参数
参数:
1. name :参数名。
2. value : 参数的具体意义,作用。
3. required : 参数是否必填。
4. dataType :参数的数据类型。
5. paramType :查询参数类型,这里有几种形式:
类型 | 作用 |
---|---|
path | 以地址的形式提交数据 |
query | 直接跟参数完成自动映射赋值 |
body | 以流的形式提交 仅支持POST |
header | 参数在request headers 里边提交 |
form | 以form表单的形式提交 仅支持POST |
在这里我被坑过一次:当我发POST请求的时候,当时接受的整个参数,不论我用body还是query,后台都会报Body Missing错误。这个参数和SpringMvc中的@RequestBody冲突,索性我就去掉了paramType,对接口测试并没有影响。
@ApiImplicitParams:
用于方法,包含多个 @ApiImplicitParam:
例:
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
@ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
- 1
- 2
- 3
@ApiModel:
用于类,表示对类进行说明,用于参数用实体类接收;
@ApiModelProperty:
用于方法,字段 ,表示对model属性的说明或者数据操作更改
例:
@ApiModel(value = "User", description = "用户")
public class User implements Serializable{
private static final long serialVersionUID = 1546481732633762837L;
/**
* 用户ID
*/
@ApiModelProperty(value = "用户ID", required = true)
@NotEmpty(message = "{id.empty}", groups = {Default.class,New.class,Update.class})
protected String id;
/**
* code/登录帐号
*/
@ApiModelProperty(value = "code/登录帐号")
@NotEmpty(message = "{itcode.empty}", groups = {Default.class,New.class,Update.class})
protected String itcode;
/**
* 用户姓名
*/
@ApiModelProperty(value = "用户姓名")
@NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
protected String name;
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
@ApiOperation:
用于方法,表示一个http请求的操作 。
@ApiOperation(value = "获取图书信息", notes = "获取图书信息", response = Book.class, responseContainer = "Item", produces = "application/json")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
@ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
@ResponseBody
public Book getBook(@PathVariable Long id, String date) {
return books.get(id);
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
@ApiResponse:
用于方法,描述操作的可能响应。
@ApiResponses:
用于方法,一个允许多个ApiResponse对象列表的包装器。
例:
@ApiResponses(value = {
@ApiResponse(code = 500, message = "2001:因输入数据问题导致的报错"),
@ApiResponse(code = 500, message = "403:没有权限"),
@ApiResponse(code = 500, message = "2500:通用报错(包括数据、逻辑、外键关联等,不区分错误类型)")})
- 1
- 2
- 3
- 4
@ApiParam:
用于方法,参数,字段说明,表示对参数的添加元数据(说明或是否必填等)
@Authorization:
声明要在资源或操作上使用的授权方案。
@AuthorizationScope:
介绍一个OAuth2授权范围。
@ResponseHeader:
响应头设置,使用方法。