Swagger2系列三 常用注解

效果图在最后，可先直接查看

Swagger常用到的注解有：

@Api
@ApiModel
@ApiModelProperty
@ApiOperation
@ApiIgnore
@ApiParam
@ApiResponse
@ApiResponses
@ResponseHeader

1. @Api

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = “测试", tags = {“测试"})

与Controller注解并列使用。 属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值，value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

2. @ApiModel

使用场景：在实体类上边使用，标记类时swagger的解析类。

概述：提供有关swagger模型的其它信息，类将在操作中用作类型时自动内省。

用法：

属性名称	数据类型	默认值	说明
value	String	类名	为模型提供备用名称
description	String	“”	提供详细类描述
parent	Class parent	Void.Class	为模型提供父类以允许描述继承关系
discriminatory	String	“”	支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型
subTypes	Class[]	{}	从此模型继承的子类型数组
reference	String	”“	指定对应类型定义的引用，覆盖指定的任何其他元数据

3. @ApiModelProperty

使用场景：使用在被 @ApiModel 注解的模型类的属性上。表示对model属性的说明或者数据操作更改 。

概述：添加和操作模型属性的数据。

用法：

属性名称	数据类型	默认值	说明
value	String	”“	属性简要说明
name	String	“”	运行覆盖属性的名称，重新属性名称
allowableValues	String	“”	限制参数可接受的值，三种方法，固定取值，固定范围
access	String	“”	过滤属性，参阅： io.swagger.core.filter.SwaggerSpecFilter
notes	String	“”	目前尚未使用
dataType	String	“”	参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型
required	boolean	false	是否为必传参数，false：非必传参数 true：必传参数
position	int	0	允许在模型中显示排序属性
hidden	boolean	false	隐藏模型属性，false：不隐藏 true：隐藏
example	String	“”	属性的示例值
readOnly	boolean	false	指定模型属性为只读，false：非只读 true：只读
reference	String	“”	指定对应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue	boolean	false	允许传空值，false：不允许传空值 true：允许传空值

4. @ApiOperation标记

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(

          value = "Find purchase order by ID",

          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",

          response = Order,

          tags = {"Pet Store"})

与Controller中的方法并列使用。

属性配置：

属性名称	备注
value	url的路径值
tags	如果设置这个值，value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码 默认 200
extensions	扩展属性

5. @ApiParam标记

ApiParam请求属性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

属性配置：

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

6. @ApiResponse

ApiResponse：响应配置，使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")

与Controller中的方法并列使用。 属性配置：

属性名称	备注
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置

7. @ApiResponses

ApiResponses：响应集配置，使用方式：

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

与Controller中的方法并列使用。 属性配置：

属性名称	备注
value	多个ApiResponse配置

8. @ResponseHeader

响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

与Controller中的方法并列使用。 属性配置：

属性名称	备注
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

9. @其他

@ApiIgnore //用在类、方法、实体上，表示文档上不会显示这个类方法或者这个实体

@ApiImplicitParams：//用在方法上包含一组参数说明；

@ApiImplicitParam：//用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

(1) paramType：参数放在哪个地方

(2) name：参数代表的含义

(3) value：参数名称

(4) dataType： 参数类型，有String/int，无用

(5) required ： 是否必要

(6) defaultValue：参数的默认值

@ApiResponses：//用于表示一组响应；

@ApiResponse：//用在@ApiResponses中，一般用于表达一个错误的响应信息；

(1) code： 响应码(int型)，可自定义

(2) message：状态码对应的响应信息

@ApiModel：//描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

@ApiModelProperty：//描述一个model的属性。

常用示例：

@ApiIgnore表示此处不会展示，

效果示例：

可调式界面