文
章
目
录
章
目
录
前两节我们讲了《Springboot如何集成Swagger》,这一节我们主要以Swagger2版本为例,讲下Swagger常用注解的使用。
Swagger常用的注解说明
- @Api:用在类上,说明该类的作用。
- @ApiOperation:注解来给API增加方法说明。
- @ApiParam:定义在参数上
- @ApiResponses:用于表示一组响应
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
l code:数字,例如400
l message:信息,例如”请求参数没填好”
l response:抛出异常的类 - @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
l @ApiModelProperty:描述一个model的属性
- @ApiImplicitParams: 用在方法上包含一组参数说明。
- @ApiImplicitParam:用来注解来给方法入参增加说明。
@ApiImplicitParam的参数说明:
参数名 | 含义 | 取值 |
---|---|---|
paramType | 指定参数放在哪个地方 |
|
name | 参数名 | |
dataType | 参数类型 | |
required | 参数是否必须传 | true | false |
value | 说明参数的意思 | |
defaultValue | 参数的默认值 |
Swagger常用的注解使用
我们先准备一个接口类UserController
@RestController
@RequestMapping("/user")
public class UserController {
@PostMapping(value = "/query-user-info")
public ResponseResult queryUserInfo(@RequestBody UserRequest userRequest) {
// 省略查询逻辑
return ResponseResult.success(new User(userRequest.getId(), "小明"));
}
}
还有几个涉及到的实体类,分别作为入参、返回类型、返回数据。
返回类型
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ResponseResult {
private Integer code;
private String message;
private Object data;
public static ResponseResult success(Object data) {
return new ResponseResult(0, "请求成功", data);
}
}
请求类型入参
@Data
@AllArgsConstructor
@NoArgsConstructor
public class UserRequest {
private Integer id;
}
返回数据
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
private Integer id;
private String name;
}
无注解情况
此时,我们还没有添加任何swagger注解,Swagger 会将接口请求或者相应的实体类信息展示在 Models
下的,运行查看如下图,发现请求体和返回类型都都显示了出来:
由此可见,前端web页面可通过看 Models
知道后端定义实体类的信息。
@ApiModel
该注解是作用于类上面的,是用来描述类的一些基本信息的。
相关属性:
value
:提供类的一个备用名,如果不设置,默认情况下将使用 class 类的名称- description:对于类,提供一个详细的描述信息
- parent:这个属性用于描述的是类的一些父类信息
- discriminator:这个属性解释起来比较麻烦,因为这个类主要体现在断言当中
- subTypes:可以通过这个属性,指定我们想要使用的子类
比如:这个为给 UserRequest
这个类添加该注解:
@Data
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户查询请求体", description = "用于接收查询请求数据")
public class UserRequest {
private Integer id;
}
可以看到这里的名字从 UserRequest
变成 用户查询请求体
了,并且多出了description描述信息。
@ApiModelProperty
它的作用是添加和操作属性模块的数据。这里我还是以UserRequest
类为例,为该类的属性添加说明:
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户查询请求体", description = "用于接收查询请求数据")
public class UserRequest {
@ApiModelProperty("用户id")
private Integer id;
}
可以看到这里对该字段类型下面有一个备注说明。
更多属性请参考《Swagger @ApiModelProperty详解》
@ApiOperation
该注解用来对某个方法/接口进行描述。这里我以 UserController
下的接口为例:
@PostMapping(value = "/query-user-info")
@ApiOperation(value = "根据id查询用户详情")
public ResponseResult queryUserInfo(@RequestBody UserRequest userRequest) {
// 省略查询逻辑
return ResponseResult.success(new User(userRequest.getId(), "小明"));
}
可以看到该接口就有了对其功能的描述信息。
更多属性请参考:《Swagger @ApiOperation 详解》
@ApiParam
该注解使用在方法上或者参数上,字段说明,表示对参数的添加元数据(说明或者是否必填等)
相关属性:
- name:参数名
- value:参数说明
- required:是否必填
这里我以 UserController
下的接口为例:
@PostMapping(value = "/query-user-infos")
@ApiOperation(value = "条件查询用户信息")
public ResponseResult queryUserInfos(
// name 用户名称 不必填
@ApiParam(value = "用户姓名", required = false) @RequestParam(required = false) String name,
// gender 用户性别 必填
@ApiParam(value = "用户性别", required = true) @RequestParam(required = true) String gender
) {
return ResponseResult.success(new User());
}
我们看到gender有必填标记,而name没有,两个属性后面也都有中中文说明其含义。