API接口自动化管理方案-Swagger

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 Editor，它是使用yaml语言的Swagger API的编辑器，支持导出yaml和json格式的接口文件；

• Swagger包含了Swagger UI，它将Swagger Editor编辑好的接口文档以html的形式展示出来；

• 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中添加依赖库

<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>2.9.2version>
dependency>

<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>2.9.2version>
dependency>

<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-bean-validatorsartifactId>
<version>2.9.2version>
dependency>

2. 创建配置类SpringFoxConfig

自己随便创建一个包,包中创建SpringFoxConfig类,类中代码如下:

package com.xiaokai.cn.springfox.config;
import java.util.Collections;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* Created by xiaokai on 2019/1/22.
*/

//定义这是一个配置类
@Configuration
//引入swagger2的标签
@EnableSwagger2
//允许swagger识别javax.validation中请求参数做了一些基本的校验，如@Min，@Max，@DecimalMin，@DecimalMax，@Size，@NotNull等
@Import(BeanValidatorPluginsConfiguration.class)
public class SpringFoxConfig {
 
 //注入实体
 @Bean
 public Docket apiDocket() {
     return new Docket(DocumentationType.SWAGGER_2).select()
             .apis(RequestHandlerSelectors.basePackage("com.xiaokai.cn.controller")) //指明扫描的controller包
             .paths(PathSelectors.ant("/**/**")).build().apiInfo(getApiInfo());	//指明拦截路径,这种路径的请求方式才会在swagger-ui.html中生成Api接口
 }

 private ApiInfo getApiInfo(){
     return new ApiInfo(
             "XXX项目自动化接口管理",		//项目名称
             "XXX项目启动于2008年8月8日,是一个关于人工智能系列的智能老年服务系统,能为老年人提供智能医疗....",		//项目说明
             "V1.2.0",	//项目版本号
             "http://localhost:8888/p/person",	//Terms of service-服务条款,要不就写成项目访问地址,点击可以直接请求该项目
             new Contact("xxx","http://xxx.com","[email protected]"),		//联系人.网址.邮箱等(可以写公司)
             "许可证",	//LICENSES
             "http://baidu.com",		//LICENSES对应的网址
             Collections.emptyList()
     );
 }
}

3.controller中标注注解

​ 对应自己的controller类标注.

package com.xiaokai.cn.controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import com.xiaokai.cn.entity.Person;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/**
 * Created by xiaokai on 2019/1/9.
 */

//@Controller+@ResponseBody
@RestController
//类里面所有请求路径的请求前缀
@RequestMapping("/p")
//对于此接口类的说明
@Api(tags = "这是一个关于person类的系列接口!")
public class PersonDemoController {

	//指明请求路径,请求方式,解析方式
	@RequestMapping(value = "person", method = RequestMethod.GET, produces = "application/json")
	//对于此接口的说明
	@ApiOperation("这是一个返回person对象的接口! 会返回一个Person对象!")
	public Person demo() {
		return new Person(3, "xiaokai", "chu", 17);
	}

	//指明请求路径,请求方式,解析方式
	@RequestMapping(method = RequestMethod.POST, path = "getPersonById/{id}")
	//对于此接口的说明
	@ApiOperation("根据id查询一个用户!")
	//@ApiParam是对于请求参数或者可变参数的解释说明
	public Person getPersonById(@ApiParam("id不能为空") @PathVariable int id) {
		return new Person(id, "si", "li", 1);
	}
}

4.参数实体类上标注注解

​ 对应自己的pojo类标注

package com.xiaokai.cn.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import javax.validation.constraints.*;

/**
 * Created by xiaokai on 2019/1/22.
 */

//实体类Person模型的解释
@ApiModel(description = "这是一个person实体类!")
public class Person {

	//指明不为空
    @NotNull
    //notes-注释、example-举例,在swagger中显示、required=true-说明这个变量的必须传入的、position-swagger中此变量的优先级，值越小优先级越高，不写默认优先级最高
    @ApiModelProperty(notes = "用户的id", example = "1", required = true, position = 0)
    private int id;
    
    //指明不为空
    @NotBlank
    //notes-注释、example-举例,在swagger中显示、required=true-说明这个变量的必须传入的、position-swagger中此变量的优先级，值越小优先级越高，不写默认优先级最高
    @ApiModelProperty(notes = "用户的名字", example = "san", required = true, position = 1)
    private String firstName;
    
    //字符串最长为20,最短为5
    @Size(min = 5,max = 20 )
    //notes-注释、example-举例,在swagger中显示、required=false-说明这个变量的不是必须传入的、position-swagger中此变量的优先级，值越小优先级越高，不写默认优先级最高
    @ApiModelProperty(notes = "用户的姓氏", example = "zhang", required = false, position = 2)
    private String lastName;
   
    //指明最小值为8
    @Min(8)
    //指明最大值为18
    @Max(18)
    //notes-注释、example-举例,在swagger中显示、required=true-说明这个变量的必须传入的、position-swagger中此变量的优先级，值越小优先级越高，不写默认优先级最高
    @ApiModelProperty(notes = "用户的年龄", example = "用户的年龄必须为整数", required = true, position = 3)
    private int age;

    @Override
    public String toString() {
        return "Person{" +
                "id=" + id +
                ", firstName='" + firstName + '\'' +
                ", lastName='" + lastName + '\'' +
                ", age=" + age +
                '}';
    }
    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public String getFirstName() {
        return firstName;
    }
    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    public String getLastName() {
        return lastName;
    }
    public void setLastName(String lastName) {
        this.lastName = lastName;
    }
    public int getAge() {
        return age;
    }
    public void setAge(int age) {
        this.age = age;
    }
    public Person(int id, String firstName, String lastName, int age) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.age = age;
    }
}

5.测试配置是否成功

​ 访问路径: http://ip地址:端口号/swagger-ui.html

​ 出现类似以下界面说明配置成功:

五、基于maven管理的SpringMVC工程与swagger整合

---

第一步: pom.xml中添加依赖

第二步: 配置springfox文件

第三部: 编写测试Controller类

1.pom.xml中添加依赖

<dependency>
  <groupId>io.springfoxgroupId>
  <artifactId>springfox-swagger2artifactId>
  <version>2.9.2version>
dependency>

<dependency>
  <groupId>io.springfoxgroupId>
  <artifactId>springfox-swagger-uiartifactId>
  <version>2.9.2version>
dependency>

<dependency>
  <groupId>io.springfoxgroupId>
  <artifactId>springfox-bean-validatorsartifactId>
  <version>2.9.2version>
dependency>

2.配置springfox文件

//定义这是一个配置类
@Configuration
//引入swagger2的标签
@EnableSwagger2
//引入swagge适配mvc的标签
@EnableWebMvc
//指明扫描包的路径
@ComponentScan("com.xiaokai.cn.controller")
//允许swagger识别javax.validation中请求参数做了一些基本的校验，如@Min，@Max，@DecimalMin，@DecimalMax，@Size，@NotNull等
@Import(BeanValidatorPluginsConfiguration.class)
public class SpringFoxConfig {
	
	//注入实体
    @Bean
    public Docket apiDocket() {
        return new Docket(DocumentationType.SWAGGER_2).groupNmae("xxx接口").select()
                .apis(RequestHandlerSelectors.any()
                .paths(PathSelectors.ant("/**/**")).build().apiInfo(getApiInfo());
    }

    private ApiInfo getApiInfo(){
        return new ApiInfo(
                "XXX项目自动化接口管理",		//项目名称
                "XXX项目启动于2008年8月8日,是一个关于人工智能系列的智能老年服务系统,能为老年人提供智能医疗....",		//项目说明
                "V1.2.0",	//项目版本号
                "http://localhost:8888/p/person",	//Terms of service-服务条款,要不就写成项目访问地址,点击可以直接请求该项目
                new Contact("阳光凯讯","http://sunkaisens.com","[email protected]"),		//联系人.网址.邮箱等(可以写公司)
                "许可证",	//LICENSES
                "http://baidu.com",		//LICENSES对应的网址
                Collections.emptyList()
        );
    }
}

3.编写测试Controller类

//@Controller+@ResponseBody
@RestController
//类里面所有请求路径的请求前缀
@RequestMapping("/p")
//对于此接口类的说明
@Api(tags = "这是一个关于person类的系列接口!")
public class PersonDemoController {

	//指明请求路径,请求方式,解析方式
	@RequestMapping(value = "person", method = RequestMethod.GET, produces = "application/json")
	//对于此接口的说明
	@ApiOperation(value = "person", notes = "这是一个返回person对象的接口! 会返回一个Person对象!",response = Person.class)
	public Person demo() {
		return new Person(3, "xiaokai", "chu", 17);
	}
}

4.实体类注解

​ 参见springboot中，配置一模一样

5.测试配置是否成功

​ 访问路径: http://ip地址:端口号/项目名/swagger-ui.html

​ 出现类似以下界面说明配置成功: