API接口自动化管理方案
API（Application Programming Interface）：
提供了对某个问题的抽象，以及客户与解决该问题的软件组件之间进行交互的方式
author–> xiaokai
一、接口管理工具使用意义
-
快速了解，查询你要使用的类库中的接口以及使用说明和使用示例，帮助开发人员提高开发的效率；
-
使用接口文档能够节省编写接口文档的时间，方便前后端之间接口的展现和调用，提高开发时的效率；
-
能够将前后端开发分离出来独立开发，甚至可以在某个接口后端还未完成但前段开发人员需要调试时可以直接 mock 数据调用，不影响前端进度；
-
帮助测试人员更好的根据接口文档进行测试。
?
二、工具选择对比
1.调研工具说明
- Postman是被大家所熟知的 页调试Chrome插件，我们常常用它来进行临时的http请求调试。幸运的是，Postman可以将调试过的请求保存到Collection中。形成的Collection就可以作为一份简单有效且支持在线测试的接口文档，使用同一账 登录就可以做到分享和同步。对QA来说，使用Postman进行接口测试和接口文档维护是同一件事情，测试即文档，维护成本也很低。
- Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件，是一个规范和完整的框架，标准的，语言无关，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
- RAP来自阿里巴巴，是一个可视化接口管理工具 通过分析接口结构，使用mock动态生成模拟数据，校验真实接口正确性， 围绕接口定义，通过一系列自动化工具提升我们的协作效率。可以在线使用，也可以选择本地部署。一个GUI的WEB接口管理工具。在RAP中，您可定义接口的URL、请求&响应细节格式等等。通过分析这些数据，RAP提供MOCK服务、测试服务等自动化工具。RAP同时提供大量企业级功能，帮助企业和团队高效的工作。
- APIDOC可以根据代码注释生成WEB API文档，支持大部分主流开发语言，Java、javascript、php、erlang、perl、python、ruby等等，相对而言，web接口的注释维护起来更加方便，不需要额外再维护一份文档。APIDOC从注释生成静态html 页文档，不仅支持项目版本 ，还支持API版本 。
- Apizza 是国内领先的在线 API saas 管理平台，支持在线的 API 调试，接口管理，在线模拟调试，快速生成api文档，导出离线版文档，快速生成文档，项目管理，团队协作以及分享，具有api跨域调试、云端存储、一键分享、智能识别参数等优点。
2.选择swagger的理由
? 相比较而言，postman和apizza是偏重测试的接口管理工具，RAP实现起来比较复杂，APIDOC实现方式和swagger相近，但是自动化管理程度没有swagger深，配置也比较麻烦，所以选择swagger作为API管理工具。
? swagger优点如下：
-
Swagger可以直接嵌入项目中，通过开发时编写注释，自动生成接口文档；
-
Swagger支持根据定义的接口导出各种语言的服务端或客户端代码。
?
三、swagger实现接口自动化原理及注解详解
####1.swagger实现接口自动化原理
? Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。鉴于swagger的强大功能，Java开源界大牛spring框架迅速跟上，它充分利用自已的优势，把swagger集成到自己的项目里，整了一个spring-swagger，后来便演变成springfox。springfox本身只是利用自身的aop的特点，通过plug的方式把swagger集成了进来，它本身对业务api的生成，还是依靠swagger来实现。
-
springfox原理：
? 在项目启动的过种中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，扫描出来的信息会生成一个json字符串，json字符串通过spring-swagger-ui渲染会形成一个可视化的html界面。
-
swagger-ui原理：
? 通过适配器自动渲染/**请求路径下的符合springfox格式的json数据，并默认渲染为swagger-ui.html统一管理显示。
2.swagger中常用注解详解
? 以下列出的是常用注解,还有其他注解,开发人员可以自行到查找！
-
配置类中:
注解 注解意义 @Configuration 定义此类为配置类 @EnableSwagger2 引入解析配置的swagger2标签 @Import(BeanValidatorPluginsConfiguration.class) 允许swagger识别javax.validation中请求参数做了一些基本的校验，如@Min，@Max，@DecimalMin，@DecimalMax，@Size，@NotNull等 -
controller类中:
注解 注解意义 @RestController 相当于@Controller+@ResponseBody @RequestMapping(“/xxx”) 可以指明这个接口的请求路径,请求方式,解析方式,同时标注在类上,指明接口类里面所有请求路径的请求前缀 @Api(tags = “xxx”) 标注在类上,对于此接口类的说明 @ApiOperation(“xxx”) 标注在接口上,对于此接口的说明 @ApiParam(“xxx”) 标注在接口方法的形参上,对于请求参数或者可变参数的解释说明 -
pojo类(实体类)中:
注解 注解意义 @ApiModel(description = “xxx”) xxx实体类模型的解释 @NotBlank 指明字符串不能为空 @NotNULL 指明Integer类型的成员变量不能为空 @ApiModelProperty(notes = “xxx”, example = “xxx”, required = true/false, position = 1) 标注在成员变量上,notes-注释、example-举例,在swagger中显示、required=true-说明这个变量的必须传入的、position-swagger中此变量的优先级，值越小优先级越高，不写默认优先级最高 @Min(x) 指明Integer类型的成员变量最小值为x @Max(x) 指明Integer类型的成员变量最大值为x @Size(min = x,max = y ) 指明String类型的成员变量的最大长度为y,最小长度为x
四、基于maven管理的SpringBoot工程与swagger整合
第一步: pom.xml中添加依赖
第二步: 添加配置类
第三部: controller类和pojo类中标注注解
1. pom.xml中添加依赖库
2. 创建配置类SpringFoxConfig
自己随便创建一个包,包中创建SpringFoxConfig类,类中代码如下:
3.controller中标注注解
? 对应自己的controller类标注.
声明：本站部分文章及图片源自用户投稿，如本站任何资料有侵权请您尽早请联系jinwei@zod.com.cn进行处理,非常感谢！