使用Swagger自动生成后台API接口
Posted L_不觉晓晓
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了使用Swagger自动生成后台API接口相关的知识，希望对你有一定的参考价值。
在现在的开发过程中还有很大一部分公司都是以口口相传的方式来进行前后端的联调，而接口文档很大一部分都只停留在了说说而已的地步，或者写了代码再写文档。 还有一点就是文档的修改，定义好的接口并不是一成不变的，可能在开发过程中文档修改不止一次的变化，这个时候就会很难受了。 只要不是强制性要求，没人会愿意写这东西，而且在写的过程中，一个字母的错误就会导致联调时候的很大麻烦，但是通过Swagger，我们可以省略了这一步，而且文档出错率近乎于零， 只要你在写代码的时候，稍加几个注解，文档自动生成。
1、在控制层Controller中添加注解来描述接口信息如:
@Api("参数配置")
@Controller
@RequestMapping("/system/config")
public class ConfigController
2、在方法中配置接口的标题信息
@ApiOperation("查询参数列表")
@ResponseBody
public TableDataInfo list(Config config)
startPage();
List<Config> list = configService.selectConfigList(config);
return getDataTable(list);
3、在系统工具-系统接口测试相关接口
注意：SwaggerConfig可以指定根据注解或者包名扫描具体的API
API详细说明
| 作用范围 | API | 使用位置 |
|---|---|---|
| 协议集描述 | @Api | 用于controller类上 |
| 对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
| 协议描述 | @ApiOperation | 用在controller的方法上 |
| Response集 | @ApiResponses | 用在controller的方法上 |
| Response | @ApiResponse | 用在 @ApiResponses里边 |
| 非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
| 非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
| 描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
api标记，用在类上，说明该类的作用。可以标记一个Controller类做为Swagger文档资源，使用方式：
@Api(value = "/user", description = "用户管理")
与Controller注解并列使用。 属性配置：
| 属性名称 | 备注 |
|---|---|
| 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 将在文档中隐藏 |
ApiOperation标记，用在方法上，说明方法的作用，每一个url资源的定义,使用方式：
@ApiOperation("获取用户信息")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| 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 | 扩展属性 |
ApiParam标记，请求属性，使用方式：
public TableDataInfo list(@ApiParam(value = "查询用户列表", required = true)User user)
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| name | 属性名称 |
| value | 属性值 |
| defaultValue | 默认属性值 |
| allowableValues | 可以不配置 |
| required | 是否属性必填 |
| access | 不过多描述 |
| allowMultiple | 默认为false |
| hidden | 隐藏该属性 |
| example | 举例子 |
ApiResponse标记，响应配置，使用方式：
@ApiResponse(code = 400, message = "查询用户失败")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| code | http的状态码 |
| message | 描述 |
| response | 默认响应类 Void |
| reference | 参考ApiOperation中配置 |
| responseHeaders | 参考 ResponseHeader 属性配置说明 |
| responseContainer | 参考ApiOperation中配置 |
ApiResponses标记，响应集配置，使用方式:
@ApiResponses( @ApiResponse(code = 400, message = "无效的用户") )
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| value | 多个ApiResponse配置 |
ResponseHeader标记，响应头设置，使用方法
@ResponseHeader(name="head",description="响应头设计")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| name | 响应头名称 |
| description | 描述 |
| response | 默认响应类 void |
| responseContainer | 参考ApiOperation中配置 |
如有不足，敬请指出
以上是关于使用Swagger自动生成后台API接口的主要内容，如果未能解决你的问题，请参考以下文章