转载

Swagger注解概览

Swagger是什么

Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已经形成一个生态圈，能够管理API的整个生命周期，从设计、文档到测试与部署。

Swagger UI ，基于Swagger-compliant API的一套可以展示优美文档的Web应用。
Swagger Editor ，一款以YAML格式编辑与管理API的工具，同时支持JSON格式的文档描述。
Swagger-Core ，Swagger的Java/Scala实现，并已集成 JAX-RS (Jersey, Resteasy, CXF…), Servlets与Play Framework。
Swagger-JS ，Swagger的Javascript版本实现。
更多。

注解	说明
`Api`	用在类上，说明该类的作用
`ApiModel`	描述一个 `Model` 的信息，使用 `@RequestBody` 的场景
`ApiModelProperty`	描述一个 `Model` 的属性
`ApiOperation`	用在方法上，说明方法的作用
`ApiParam`	请求属性
`ApiResponse`	用在 `@ApiResponses` 中，一般用于表达一个错误的响应配置
`ApiResponses`	用于表示一组响应集配置
`ResponseHeader`	响应头设置
`ApiImplicitParams`	用在方法上包含一组参数说明
`ApiImplicitParam`	用在 `@ApiImplicitParams` 注解中，指定一个请求参数的各个方面

属性	说明
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	返回的对象,默认响应类 Void
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200
message	状态码对应的响应信息
extensions	扩展属性
name	属性名称
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
example	举例子
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
description	头描述
paramType	参数放在哪个地方
dataType	参数类型，有String/int，无用