2023年7月10日发(作者：)

API接⼝⾃动化管理⽅案-SwaggerAPI接⼝⾃动化管理⽅案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实现接⼝⾃动化原理及注解详解####r实现接⼝⾃动化原理 Swagger是⼀款RESTFUL接⼝的⽂档在线⾃动⽣成+功能测试功能软件。鉴于swagger的强⼤功能，开源界⼤⽜框架迅速跟上，它充分利⽤⾃已的优势，把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数据，并默认渲染为统⼀管理显⽰。r中常⽤注解详解 以下列出的是常⽤注解,还有其他注解,开发⼈员可以⾃⾏到查找！配置类中:注解@Configuration@EnableSwagger2注解意义定义此类为配置类引⼊解析配置的swagger2标签允许swagger识别tion中请求参数做了⼀些基本的校验，如@Min，@Max，@DecimalMin，@DecimalMax，@Size，@NotNull等@Import()controller类中:注解@RestController@RequestMapping("/xxx")@Api(tags = “xxx”)@ApiOperation(“xxx”)@ApiParam(“xxx”)注解意义相当于@Controller+@ResponseBody可以指明这个接⼝的请求路径,请求⽅式,解析⽅式,同时标注在类上,指明接⼝类⾥⾯所有请求路径的请求前缀标注在类上,对于此接⼝类的说明标注在接⼝上,对于此接⼝的说明标注在接⼝⽅法的形参上,对于请求参数或者可变参数的解释说明pojo类(实体类)中:注解@ApiModel(description = “xxx”)@NotBlank@NotNULL@ApiModelProperty(notes = “xxx”,example = “xxx”, required = true/false,position = 1)@Min(x)@Max(x)@Size(min = x,max = y )注解意义xxx实体类模型的解释指明字符串不能为空指明Integer类型的成员变量不能为空标注在成员变量上,notes-注释、example-举例,在swagger中显⽰、required=true-说明这个变量的必须传⼊的、position-swagger中此变量的优先级，值越⼩优先级越⾼，不写默认优先级最⾼指明Integer类型的成员变量最⼩值为x指明Integer类型的成员变量最⼤值为x指明String类型的成员变量的最⼤长度为y,最⼩长度为x四、基于maven管理的SpringBoot⼯程与swagger整合第⼀步: 中添加依赖第⼆步: 添加配置类第三部: controller类和pojo类中标注注解1. 中添加依赖库foxspringfox-swagger22.9.2foxspringfox-swagger-ui2.9.2foxspringfox-bean-validators2.9.22. 创建配置类SpringFoxConfig⾃⼰随便创建⼀个包,包中创建SpringFoxConfig类,类中代码如下:package ;import tions;import ;import uration;import ;import lidatorPluginsConfiguration;import lectors;import tHandlerSelectors;import o;import t;import ntationType;import ;import Swagger2;/*** Created by xiaokai on 2019/1/22.*///定义这是⼀个配置类@Configuration//引⼊swagger2的标签@EnableSwagger2//允许swagger识别tion中请求参数做了⼀些基本的校验，如@Min，@Max，@DecimalMin，@DecimalMax，@Size，@NotNull等@Import()public class SpringFoxConfig {

//注⼊实体 @Bean public Docket apiDocket() { return new Docket(R_2).select() .apis(ckage("ller")) //指明扫描的controller包 .paths(("/**/**")).build().apiInfo(getApiInfo()); //指明拦截路径,这种路径的请求⽅式才会在中⽣成Api接⼝ } private ApiInfo getApiInfo(){ return new ApiInfo( "XXX项⽬⾃动化接⼝管理", //项⽬名称 "XXX项⽬启动于2008年8⽉8⽇,是⼀个关于⼈⼯智能系列的智能⽼年服务系统,能为⽼年⼈提供智能医疗....", //项⽬说明 "V1.2.0", //项⽬版本号 "localhost:8888/p/person", //Terms of service-服务条款,要不就写成项⽬访问地址,点击可以直接请求该项⽬ new Contact("xxx","","xxx@"), //联系⼈.⽹址.邮箱等(可以写公司) "许可证", //LICENSES "", //LICENSES对应的⽹址 ist() ); }}ller中标注注解 对应⾃⼰的controller类标注.package ller;import riable;import tMapping;import tMethod;import ntroller;import ;import ;import ration;import am;/** * Created by xiaokai on 2019/1/9. *///@Controller+@ResponseBody@RestController//类⾥⾯所有请求路径的请求前缀@RequestMapping("/p")//对于此接⼝类的说明@Api(tags = "这是⼀个关于person类的系列接⼝!")public class PersonDemoController { //指明请求路径,请求⽅式,解析⽅式 @RequestMapping(value = "person", method = , produces = "application/json") //对于此接⼝的说明 @ApiOperation("这是⼀个返回person对象的接⼝! 会返回⼀个Person对象!") public Person demo() { return new Person(3, "xiaokai", "chu", 17); } //指明请求路径,请求⽅式,解析⽅式 @RequestMapping(method = , path = "getPersonById/{id}") //对于此接⼝的说明 @ApiOperation("根据id查询⼀个⽤户!") //@ApiParam是对于请求参数或者可变参数的解释说明 public Person getPersonById(@ApiParam("id不能为空") @PathVariable int id) { return new Person(id, "si", "li", 1); }}4.参数实体类上标注注解 对应⾃⼰的pojo类标注package ;import el;import elProperty;import aints.*;/** * 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) { = id; } public String getFirstName() { return firstName; } public void setFirstName(String firstName) { ame = firstName; } public String getLastName() { return lastName; } public void setLastName(String lastName) { me = lastName; } public int getAge() { return age; } public void setAge(int age) { = age; } public Person(int id, String firstName, String lastName, int age) { = id; ame = firstName; me = lastName; = age; }}5.测试配置是否成功 出现类似以下界⾯说明配置成功:五、基于maven管理的SpringMVC⼯程与swagger整合第⼀步: 中添加依赖第⼆步: 配置springfox⽂件第三部: 编写测试Controller类中添加依赖 fox springfox-swagger2 2.9.2 fox springfox-swagger-ui 2.9.2 fox springfox-bean-validators 2.9.22.配置springfox⽂件//定义这是⼀个配置类@Configuration//引⼊swagger2的标签@EnableSwagger2//引⼊swagge适配mvc的标签@EnableWebMvc//指明扫描包的路径@ComponentScan("ller")//允许swagger识别tion中请求参数做了⼀些基本的校验，如@Min，@Max，@DecimalMin，@DecimalMax，@Size，@NotNull等@Import()public class SpringFoxConfig {

//注⼊实体 @Bean public Docket apiDocket() { return new Docket(R_2).groupNmae("xxx接⼝").select() .apis(() .paths(("/**/**")).build().apiInfo(getApiInfo()); } private ApiInfo getApiInfo(){ return new ApiInfo( "XXX项⽬⾃动化接⼝管理", //项⽬名称 "XXX项⽬启动于2008年8⽉8⽇,是⼀个关于⼈⼯智能系列的智能⽼年服务系统,能为⽼年⼈提供智能医疗....", //项⽬说明 "V1.2.0", //项⽬版本号 "localhost:8888/p/person", //Terms of service-服务条款,要不就写成项⽬访问地址,点击可以直接请求该项⽬ new Contact("阳光凯讯","","chuxiaokai@"), //联系⼈.⽹址.邮箱等(可以写公司) "许可证", //LICENSES "", //LICENSES对应的⽹址 ist() ); }}3.编写测试Controller类//@Controller+@ResponseBody@RestController//类⾥⾯所有请求路径的请求前缀@RequestMapping("/p")//对于此接⼝类的说明@Api(tags = "这是⼀个关于person类的系列接⼝!")public class PersonDemoController { //指明请求路径,请求⽅式,解析⽅式 @RequestMapping(value = "person", method = , produces = "application/json") //对于此接⼝的说明 @ApiOperation(value = "person", notes = "这是⼀个返回person对象的接⼝! 会返回⼀个Person对象!",response = ) public Person demo() { return new Person(3, "xiaokai", "chu", 17); }}4.实体类注解 参见springboot中，配置⼀模⼀样5.测试配置是否成功 出现类似以下界⾯说明配置成功: