Swagger 常用注解使用详解

转载简书：https://www.jianshu.com/p/12f4394462d5

 

swagger常用标识主要有以下几种：

1、@Api

@Api主要在类上使用，说明该类作用。可以标识一个controller类作为swagger文档资源来使用。与controller注解同时使用。

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

属性名称	备注
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、@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	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	扩展属性

3、@ApiParam

@ApiParam请求属性

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

4、@ApiResponse

@ApiResponse是响应配置。@ApiResponse（code=“200”，message=“响应成功”）

5、@ApiResponses

@ApiResponses是响应集配置，在其中配置单个@ApiResponse

@ApiResponses({

@ApiResponse(code = "200"), message = "响应成功"，

@ApiResponse(code = "400"), message = "响应失败"，

})