swagger2 介绍+注解说明
简介:
为什么要用swagger，我的理由是方便，作为后端开放人员，最烦的事就是自己写接口文档和前端交互是不是需要各种参数很繁琐，项目集成swagger后就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。
优势:
1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便。
2.提供 Web 页面在线测试 API：有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
示例如图下:
swagger基本注解使用
注解及其使用如下(对应注解)：
| 注解 | 作用 | 使用位置 |
|---|---|---|
| @Api | 表示对类的说明常用参数 | 类上面 |
| @ApiOperation | 说明方法的用途、作用 | 方法上面 |
| @ApiModel | 表示一个返回响应数据的信息 | 响应类 |
| @ApiModelProperty | 描述响应类的属性 | 属性 |
| @ApiIgnore | 忽略某个字段使之不显示在文档中 | 属性 |
一、 @Api：用在请求的类上，表示对类的说明常用参数
| 参数 | 描述 |
|---|---|
| tags | 说明该类的作用，非空时将覆盖value的值 |
| value | 描述类的作用 |
| description | 对api资源的描述，在1.5版本后不再支持 |
| basePath | 基本路径可以不配置，在1.5版本后不再支持 |
| position | 如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持 |
| produces | 设置MIME类型列表（output），例：“application/json, application/xml”，默认为空 |
| authorizations | 获取授权列表（安全声明），如果未设置，则返回一个空的授权值 |
| hidden | 默认为false， 配置为true 将在文档中隐藏 |
示例:
@CrossOrigin
@RestController
@RequestMapping("/customer/information")
@Api(tags = "定制橱柜~客户信息")
public class CrmCustomersController{} 接口文档示例:
二、@ApiOperation：用在请求的方法上，说明方法的用途、作用
| 参数 | 描述 |
|---|---|
| value | 说明方法的用途、作用 |
| notes | 方法的备注说明 |
| tags | 操作标签，非空时将覆盖value的值 |
| response | 响应类型（即返回对象） |
| responseContainer | 声明包装的响应容器（返回对象类型）。有效值为 “List”, “Set” or “Map”。 |
| responseReference | 指定对响应类型的引用。将覆盖任何指定的response（）类 |
| httpMethod | 指定HTTP方法，“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
| responseHeaders | 响应头列表 |
| code | 响应的HTTP状态代码。默认 200 |
| hidden | 默认为false， 配置为true 将在文档中隐藏 |
示例:
@ApiOperation(value = "供应商~导购(状态流转)")
@RequestMapping(value = "queryStateExchange", method = RequestMethod.POST)
public PmpResult queryStateExchange () int pageNum,String state){}接口文档示例:
三、@ApiModelProperty:用在属性上，描述响应类的属性
| 参数 | 描述 |
|---|---|
| value | 此属性的简要说明。 |
| name | 允许覆盖属性名称 |
| allowableValues | 限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值 |
| access | 允许从API文档中过滤属性。 |
| notes | 目前尚未使用。 |
| dataType | 参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称。 |
| required | 参数是否必传，默认为false |
| position | 允许在类中对属性进行排序。默认为0 |
| hidden | 允许在Swagger模型定义中隐藏该属性。 |
| example | 属性的示例。 |
| readOnly | 将属性设置为只读 |
| reference | 指定对相应类型定义的引用，覆盖指定的任何参数值 |
示例:
接口文档示例:
四、 @ApiIgnore 忽略某个属性，使之不显示在swagger文档中显示
未加注解前示例:
加注解后示例:
@ApiOperation(value = "客户列表")
@RequestMapping(value = "customerlist", method = RequestMethod.GET)
public PmpResult queryCustomerList (@ApiIgnore @RequestParam(value="pageNum",defaultValue="1") int pageNum, @RequestParam(value="pageSize",defaultValue="10") int pageSize, String customersno, String customersname, String daogouid){}加注解后接口文档示例:
五、@ApiImplicitParams 用法
示例:
@ApiImplicitParams({ @ApiImplicitParam(value="客户编号(精确命中)",name="customersno",dataType="Stirng",paramType = "query"),
@ApiImplicitParam(value="类型(04:门 05:口)",name="state",dataType="Stirng",paramType = "query"),
@ApiImplicitParam(value="订单主表Uid",name="parentId",dataType="Stirng",paramType = "query")})
@RequestMapping(value = "queryByDoorOrderlist", method = RequestMethod.POST)
@ApiOperation(value = "基础项目~订单~木门")
public PmpResult queryByDoorOrderlist(String customersno, String state,String parentId){}接口文档示例: 显示描述信息
以上就是常用的注解示例，如需要其他注解可自行尝试。