Swagger注释API详细说明
详细说明:
作用范围 |
API |
使用位置 |
对象属性 |
@ApiModelProperty |
用在出入参数对象的字段上 |
协议集描述 |
@Api |
用于controller类上 |
协议描述 |
@ApiOperation |
用在controller的方法上 |
Response集 |
@ApiResponses |
用在controller的方法上 |
Response |
@ApiResponse |
用在 @ApiResponses里边 |
非对象参数集 |
@ApiImplicitParams |
用在controller的方法上 |
非对象参数描述 |
@ApiImplicitParam |
用在@ApiImplicitParams的方法里边 |
描述返回对象的意义 |
@ApiModel |
用在返回对象类上 |
一、@ApiImplicitParam
可用在@ApiImplicitParams注解中,也可以单独使用,指定一个请求参数的各个方面
属性 |
取值 |
作用 |
paramType |
|
查询参数类型 |
|
path |
以地址的形式提交数据 |
|
query |
直接跟参数完成自动映射赋值 |
|
body |
以流的形式提交 仅支持POST |
|
header |
参数在request headers 里边提交 |
|
form |
以form表单的形式提交 仅支持POST |
dataType |
|
参数的数据类型 只作为标志说明,并没有实际验证 |
|
Long |
|
|
String |
|
name |
|
接收参数名 |
value |
|
接收参数的意义描述 |
required |
|
参数是否必填 |
|
true |
必填 |
|
false |
非必填 |
defaultValue |
|
默认值 |
例子:
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户编号(必填)", required = true, dataType = "Long", paramType = "path"),
@ApiImplicitParam(name = "name", value = "用户名称", dataType = "String"),
@ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Integer"),
@ApiImplicitParam(name = "user", value = "用户实体User(不填: 默认值)", dataType = "User", defaultValue = "User")
})
二、@ApiOperation
我们添加这个注解到任何controller的rest方法上来给方法添加基本的描述
属性 |
作用 |
value |
接口说明 |
httpMethod |
接口请求方式 |
response |
接口返回参数类型 |
notes |
接口发布说明 |
例子:
@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
三、@ApiModelProperty
这个注解用来在数据模型对象中的属性上添加一些描述,会在Swagger UI中展示模型的属性
属性 |
作用 |
value |
字段说明 |
name |
重写属性名字 |
dataType |
重写属性类型 |
required |
是否必填 |
example |
举例说明 |
hidden |
隐藏 |
例子:
public class User implements Serializable{
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用户名",name="username",example="xingguo")
private String username;
@ApiModelProperty(value="状态",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
@ApiModelProperty(value="id数组",hidden=true)
private String[] ids;
private List<String> idList;
//省略get/set
}
四、@ApiResponse
我们添加这个注解到任何controller的rest方法上来给方法添加基本的描述
属性 |
作用 |
code |
数字, 例如400 |
message |
信息, 例如"请求参数没填好" |
response |
抛出异常的类 |
例子:
@ApiResponses(value = { @ApiResponse(code = 400, message = "Invalid ID supplied"),
@ApiResponse(code = 404, message = "Pet not found") })
public Response getPetById(...) {...}
五、@Api
我们可以添加这个注解在controller上,去添加一个基本的controller说明
例子:
@Api(value = "UserController", description = "user控制器")
@RestController
@RequestMapping(value = "/users") // 通过这里配置使下面的映射都在/users下,可去
public class UserController {
...
}