API工具--Swagger

一、Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful 风格的 Web 服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口，可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

二：为什么要使用swaager?

程序员最讨厌的两件事：1、写注释写文档 2、别人不写注释、不写文档。

2.1、对于后端开发人员来说不用再手写WiKi接口拼大量的参数，避免手写错误对代码侵入性低，采用全注解的方式，开发简单方法参数名修改、增加、减少参数都可以直接生效，不用手动维护缺点：增加了开发成本，写接口还得再写一套参数配置

2.2、对于前端开发来说后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

2.3、对于测试对于某些没有前端界面UI的功能，可以用它来测试接口操作简单，不用了解具体代码就可以操作操作简单，不用了解具体代码就可以操作。

三、Swaager常用注解说明:

@ApiModel：用于类，描述一个model的信息

@ApiModelProperty：用于方法，字段，表示对model属性的说明

@Api：用于类，表示标识这个类是swagger的资源，并说明该类的作用

@ApiOperation：用于方法，给API增加方法说明，说明方法的具体作用

@ApiParam：用在请求方法的参数上，表示对参数的说明

@ApiImplicitParam: 用在方法上表示单独的请求参数

@ApiResponses：用在请求的方法上,表示一组响用

四、Swagger 总结

优点：

1、编写代码的过程中，可以实时的产出接口文档，对于文档的维护非常方便。

2、文档结构清晰，界面美观，便于项目内部交流。

3、方便测试人员和前端开发人员了解API。

4、支持通过API规范生成客户端和服务器代码骨架代码，加速开发。

缺点：

1、对代码的嵌入性比较强。

2、无法更换主题。