浅谈Swagger注解

@Api

使用场景：在 Rest 接口类上边使用。
概述
标记类为 Swagger 资源类，运行时有效。
Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。

属性

属性名称	数据类型	默认值	说明
value	String	“”	隐式设置操作的标记，遗留支持(读取 description)
tags	String[]	“”	对接口进行分组,起到说明该类的作用
description			对api资源的描述
produces	String	“”	采用逗号分隔的 content types,例如:application/json,application/xml 生成JSON和XML的输出
consumes	String	“”	采用逗号分隔的 content types，例如: application/json,application/xml 会接收JSON和XML的输入
protocols	String	“”	采用逗号分隔的可用协议，例如:http,https,ws,wss
authorizations	Authorization[]	“”	授权列表
hidden	boolean	false	隐藏此资源下的操作, 和 @ApiOperation注解中的hidden组合使用可以隐藏该接口

常用的参数是：

tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"

在SpringMvc中的配置如下：

@Controller
@RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE})
@Api(value = "/pet", description = "Operations about pets")
public class PetController {

}

@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"})

属性

属性名称	数据类型	默认值	说明
value	String		接口简要说明，120字符或更少
notes	String	“”	接口详细描述
tags	String[]	“”	tag 列表，可用于按自愿或任何其它限定符对操作进行逻辑分组
response	Class<?>	Void.class	接口返回类型
responseContainer	String	“”	声明包装响应的容器。有效值为 List,Set,Map，任何其它值都将被忽略
responseReference	String	“”	指定对响应类型的引用，本地/远程引用，并将覆盖任何其它指定的response()类
httpMethod	String	“”	请求方式:“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”,如果未指定则使用除"PATH"之外的其它所有
nickname	String	“”	第三方工具使用operationId来唯一表示此操作
produces	String	“”	采用逗号分隔的 content types 类型的返回数据，例如:application/json,application/xml
consumes	String	“”	采用逗号分隔的 content types 类型的入参数据类型，例如:application/json,application/xml
protocols	String	“”	指定协议类型:http,https,ws,wss,多个协议使用逗号进行分隔
authorizations	Authorization[]	@Authorization(value = “”)	获取此操作的授权列表
hidden	boolean	false	是否隐藏操作列表中的操作
responseHeaders	ResponseHeader[]	@ResponseHeader(name = “”, response = Void.class)	指定 response header 信息列表
code	int	200	HTTP返回状态码
extensions	Extension[]	@Extension(properties = @ExtensionProperty(name = “”, value = “”))	可选的扩展数组

常用参数：

value="方法的用途和作用"    
notes="方法的注意事项和备注"    
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"} 
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）

在SpringMvc中的配置如下：

@RequestMapping(value = "/order/{orderId}", method = GET)
  @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.class,
      tags = { "Pet Store" })
   public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId)
      throws NotFoundException {
    Order order = storeData.get(Long.valueOf(orderId));
    if (null != order) {
      return ok(order);
    } else {
      throw new NotFoundException(404, "Order not found");
    }
  }

@ApiImplicitParams 和 @ApiImplicitParam

@ApiImplicitParams
使用场景:在 Rest 接口方法上使用来指定请求参数

概述
在 Rest 接口方法上使用来指定请求参数

属性

属性名称	数据类型	默认值	说明
value	ApiImplicitParam[]	API	可用的参数列表

@ApiImplicitParam
使用场景
场景一：在 Rest 接口上单独使用
@ApiImplicitParam 在 Rest接口上单独使用的时候，表示单个请求参数

场景二：在 Rest 接口上和 @ApiImplicitParams 组合使用
@ApiImplicitParam 在 Rest接口上和 @ApiImplicitParams 组合时候，表示多个请求参数

概述
表示 Rest 接口的单个请求参数，可与 @ApiImplicitParams 组合使用来表示多个请求参数

属性

属性名称	数据类型	默认值	说明
name	String	“”	参数名称(实体类字段名称)
value	String	“”	参数简要说明
defaultValue	String	“”	描述参数的默认值
allowableValues	String	“”	限制此参数接收的值，可使用的值或值得范围
required	boolean	false	指定是否为必填参数,false:非必传参数; true:必传参数
access	String	“”	参数过滤，参考: io.swagger.core.filter.SwaggerSpecFilte
allowMultiple	boolean	false	指定参数是否可以通过多次出现来接收多个值
dataType	String	“”	参数的数据类型，可以使类名或原始数据类型
dataTypeClass	Class<?>	Void.class	参数的类，如果提供则覆盖 dataType
paramType	String	“”	参数的参数类型，有效值为 path, query, body, header, form
example	String	“”	非请求体(body)参数的单个请求示例
examples	Example	@Example(value = @ExampleProperty(mediaType = “”, value = “”))	参数示例，仅适用于 BodyParameters(请求体类型的)
type	String	“”	添加覆盖检测到的类型的功能
format	String	“”	添加提供自定义格式的功能
allowEmptyValue	boolean	false	添加将 format 设置为空的功能
readOnly	boolean	false	添加被指定为只读的能力
collectionFormat	String	“”	添加使用 array 类型 collectionFormat 的功能

联系：

• @ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam
• @ApiImplicitParam：用于方法，表示单独的请求参数

常用参数：

name="参数ming" 
value="参数说明" 
dataType="数据类型" 
paramType="query" 表示参数放在哪里
    · header 请求参数的获取：@RequestHeader
    · query   请求参数的获取：@RequestParam
    · path（用于restful接口） 请求参数的获取：@PathVariable
    · body（不常用）
    · form（不常用） 
defaultValue="参数的默认值"
required="true" 表示参数是否必须传

@ApiParam

@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明

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

属性配置：

常用参数：

name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required="true" 表示属性是否必填，默认为false

在SpringMvc中的配置如下：

 public ResponseEntity<Order> getOrderById(
      @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true)
      @PathVariable("orderId") String orderId)

@ApiModel和@ApiModelProperty

版本

springfox-swagger2	(version = 2.9.2)
swagger-bootstrap-ui	(version = 1.9.6)
swagger-models	(version =1.6.1)

@ApiModel
使用场景：在实体类上边使用，标记类是swagger的解析类，也就是说是用于响应实体类上，用于说明实体作用的

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

@ApiModelProperty
使用场景：使用在被 @ApiModel 注解的模型类的属性上，即是用在属性上，描述实体类的属性

属性名称	数据类型	默认值	说明
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:允许传空值

@ApiResponses 和 @ApiResponse

@ResponseHeader

@Authorization 和 @AuthorizationScope

@SwaggerDefinition

@ExternalDocs