Swagger 常用注解使用详解
Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。.
做最好的教育服务商
Swagger是为REST API 自动生成接口文档和客户端使用AIP示例代码的完整解决方案，它帮助研发人员做到调用端代码、服务端代码以及接口文档的一致性。
Swagger让前端开发人员在看不到源码的情况下能发现和理解各种API服务的功能。当API服务通过Swagger定义。
“API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。”
Swagger常用到的注解有：
- Api 接口集描述，一般用于controller类上。
- ApiModel 描述返回对象的意义，用在返回对象类上。
- ApiModelProperty 对象属性，用在出入参数对象的字段上。
- ApiOperation 接口描述，用在controller的方法上
- ApiParam 请求参数
- ApiResponses Response集，用在controller方法上
- ApiResponse
- ResponseHeader 作为 @ApiResponse 的属性，作为返回数据的一部分，指定返回 header 信息
1、@Api
@Api主要在类上使用，说明该类作用。可以标识一个controller类作为swagger文档资源来使用。与controller注解同时使用。
@Api(value = "/user", description = "用户管理")| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | 例如, “application/json, application/xml” |
| consumes | 例如, “application/json, application/xml” |
| protocols | 通讯协议: 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 = “响应失败”，
})
6、@ResponseHeader
| 属性名称 | 备注 |
|---|---|
| name | 属性名称 |
| description | 描述 |
| response | Header’s data type |
| hidden | 隐藏该属性 |
| responseContainer | 声明包装响应的容器，有效值为List或Set，任何其他值都将被覆盖 |