接⼝⽂档与接⼝⽂档管理⼯具
⽬录
1、接⼝⽂档
1.定义：在项⽬开发汇总，web项⽬的前后端是分离开发的。应⽤程序的开发，需要由前后端⼯程师共同定义接⼝，编写接⼝⽂档，之后⼤家都根据这个接⼝⽂档进⾏开发，到项⽬结束前都要⼀直维护。
2.功能与⽬的：项⽬开发过程中前后端⼯程师有⼀个统⼀的⽂件进⾏沟通交流开发，项⽬维护或者项⽬⼈员更迭的时候，⽅便后期⼈员查看、维护。
3.接⼝⽂档规范：
⾸先了解⼀下接⼝：
请求⽅法GET PUT POST DELETEpostman在线测试
url 以/a开头，如果需要登录才能调⽤的接⼝（如新增、修改；前台的⽤户个⼈信息，资⾦信息等）后⾯需要加/u，
即：/a/u；中间⼀般放表名或者能表达这个接⼝的单词。get⽅法，若果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾。uri地址⾥不逊于出现⼤写字母，如果是两个单词拼接，⽤/分开
请求参数和返回参数字段类的属性
说明中⽂释义
类型
属性的类型，只有
String、Number、
Object、Array四⼤
类
备注
⼀些解释语，或者写
简单的⽰例
是否必填
返回参数只返回接⼝调⽤成功或者失败：code、reason 返回参数：字段、类型
⼀份规范的接⼝⽂档除了上⾯提到的请求⽅法、url、请求参数、返回参数以外，还应该添加接⼝⽰例、接⼝⽂档版本号、版本修改内容、版本修改时间、修改⼈，错误代码等。
5.⽰例：接⼝⽂档⽰例（来源：⽹络）
2、接⼝⽂档管理⼯具
-Postman、Swagger、RAP、DOClever对⽐介绍
在项⽬开发测试中，接⼝⽂档是贯穿始终的。前后端开发需要在开发前期进⾏接⼝定义并形成⽂档，QA在功能测试和接⼝测试的环节也需要依赖于这些接⼝⽂档进⾏测试。接⼝⽂档往往以最简单的静态⽂档的形态存在。然⽽在紧张的敏捷开发模式下，随着版本迭代，很多接⼝发⽣了变化或者被废弃，⽽开发⼏乎不会在后期去更新这种静态⽂档。QA⼈员阅读“过期”的接⼝⽂档是⼀件痛苦的事情，与开发的沟通成本不降反升。⽽这些不便于及时维护的静态⽂档，随着时间的推移最终⽆⼈问津。因此，我们想要到⼀种长期可维护且轻量便捷的接⼝⽂档⼯具。
Postman是被⼤家所熟知的⽹页调试Chrome插件，我们常常⽤它来进⾏临时的http请求调试。幸运的是，Postman可以将调试过的请求保存到Collection中。形成的Collection就可以作为⼀份简单有效且⽀持在线测试的接⼝⽂档，使⽤同⼀账号登录就可以做到分享和同步。对QA来说，使⽤Postman进⾏接⼝测试和接⼝⽂档维护是同⼀件事情，测试即⽂档，维护成本也很低。
Swagger是⼀个规范和完整的框架，⽤于⽣成、描述、调⽤和可视化RESTful风格的Web服务。简单来说，Swagger是⼀个功能强⼤的接⼝管理⼯具，并且提供了多种编程语⾔的前后端分离解决⽅案。Swagger主要包含了以下4个部分：
1. Swagger可以直接嵌⼊项⽬中，通过开发时编写注释，⾃动⽣成接⼝⽂档；
2. Swagger包含了SwaggerEditor，它是使⽤yaml语⾔的Swagger API的编辑器，⽀持导出yaml和json格式的接⼝⽂件；
3. Swagger包含了SwaggerUI，它将Swagger Editor编辑好的接⼝⽂档以html的形式展⽰出来；
4. Swagger⽀持根据定义的接⼝导出各种语⾔的服务端或客户端代码。
其中1和4是更加⾯向开发的内容，开发团队要有⾃动⽣成⽂档的需求，在开发和⾃测中遵循前后端分离。⽽2和3是相对可以独⽴出来的、可供QA⼈员参考的接⼝⽂档管理⽅案，也是我们主要关注的部分。
Swagger提供了SwaggerEditor和Swagger UI的在线demo，如下图。可以看出，Swagger可以完整地定义⼀个接⼝的内容，包括各个参数、返回值的具体结构、类型，SwaggerEditor可以实时进⾏编辑并在线调试。编辑好的API可以导出为json⽂件，使⽤Swagger UI打开即可以看到更美观的接⼝⽂档。
Swagger Editor和SwaggerUI的本地部署⼗分简单，这两者都可以直接从Github上下载源码，将其部署到本地Tomcat服务器上，然后通过浏览器访问即可。官⽅还提供了其他⼏种部署⽅式，具体步骤在帮助⽂档中有详细说明，这⾥不再赘述。
RAP是阿⾥的⼀套完整的可视化接⼝管理⼯具，可以定义接⼝结构，动态⽣成模拟数据，校验真实接⼝正确性。不仅如此，RAP围绕接⼝定义，提供了⼀系列包括团队管理、项⽬管理、⽂档版本管理、mock插件等服务。
有关RAP的使⽤，RAP官⽹提供了⾮常详细的wiki和视频教程。与Swagger需要使⽤标记语⾔编写不同，RAP可以完全可视化地定义项⽬相关信息，定义接⼝的请求响应等等，学习成本较低。RAP还为后端开发⼈员提供了校验接⼝的功能，为前端开发⼈员提供了mock数据的⼯具等。
DOClever是⼀个可视化接⼝管理⼯具，可以分析接⼝结构，校验接⼝正确性， 围绕接⼝定义⽂档，通过⼀系列⾃动化⼯具提升我们的协作效率。DOClever前后端全部采⽤了javascript来作为开发语⾔，前
端⽤的是vue+element UI，后端是express+mongodb，这样的框架集成了⾼并发，迭代快的特点，保证系统的稳定可靠。
功能如下：
1.可以对接⼝信息进⾏编辑管理，⽀持get,post,put,delete,patch 五种⽅法，⽀持 https 和 https 协议，并且⽀持
query，body，json，raw，rest，formdata 的参数可视化编辑。同时对 json 可以进⾏⽆限层次可视化编辑。并且，状态码，代码注⼊，markdown ⽂档等附加功能应有尽有。
2.接⼝调试运⾏，可以对参数进⾏加密，从md5 到 aes ⼀应俱全，返回参数与模型实时分析对⽐，给出不⼀致的地⽅，出接⼝可能出现的问题。如果你不想⼿写⽂档，那么试试接⼝的数据⽣成功能，可以对接⼝运⾏的数据⼀键⽣成⽂档信息。
4.⽀持 postman，rap，swagger 的导⼊，⽅便你做⽆缝迁移，同时也⽀持 html ⽂件的导出，⽅便你离线浏览！
5.项⽬版本和接⼝快照功能并⾏，你可以为⼀个项⽬定义 1.0，1.1，1.2 版本，并且可以⾃由的在不同版本间切换回滚，再也不怕接⼝信息的遗失，同时接⼝也有快照功能，当你接⼝开发到⼀半或者接⼝需求变更的时候，可以随时查看之前编辑的接⼝信息。
6.⾃动化测试功能，⽬前市⾯上类似平台的接⼝⾃动化测试⼤部分都是伪⾃动化，对于⼀个复杂的场景，⽐如获取验证码，登陆，获取订单列表，获取某个特定订单详情这样⼀个上下⽂关联的⼀系列操作⽆能为⼒。⽽ DOClever 独创的⾃动化测试功能，只需要你编写极少量的javascript 代码便可以在⽹页⾥完成这样⼀系列操作，同时，DOClever 还提供了后台定时批量执⾏测试⽤例并把结果发送到团队成员邮箱的功能，你可以及时获取接⼝的运⾏状态。
7.团队协作功能，很多类似的平台这样的功能是收费的，但是 DOClever 觉得好东西需要共享出来，你可以新建⼀个团队，并且把团队内的成员都拉进来，给他们分组，给他们分配相关的项⽬以及权限，发布团队公告等等。
DOClever 开源免费，⽀持内⽹部署，很多公司考虑到数据的安全性，不愿意把接⼝放到公⽹上，没有关系，DOClever 给出⼀个⽅便快捷的解决⽅案，你可以把平台放到⾃⼰的内⽹上，完全不需要连接外⽹，同时功能⼀样也不少，即便是对于产品的升级，DOClever 也提供了很便捷的升级⽅案！
总结
Postman是⼀个测试向的API⼩⼯具，可以⾮常轻量地维护⼀份“测试记录”，适合⼩的测试团队⾃⼰使⽤并维护。Swagger丰富且独⽴的各个功能使得它可以被应⽤在各种需求下，不论是开发还是测试都可以使⽤这个⼯具，来优化⾃⼰的开发过程，进⾏接⼝⽂档维护、接⼝测试等；但Swagger的学习和接⼊成本相对较⾼，需要开发与测试的深⼊配合。RAP的应⽤范围⾮常明确，是⼀个⾯向开发⼈员⾃测和联调的⼯具性平台，它更适合以开发为核⼼对接⼝进⾏维护，但⽬前基本不在维护。DOClever是⼀款功能⽐较强⼤的平台，在国内好评率很⾼，⽽且产品完全免费开源，可线下部署；同时产品更新迭代⽐较频繁，可以看出他们也是在⽤⼼做这个产品；
3、Swagger
（）
相信⽆论是前端还是后端开发，都或多或少地被接⼝⽂档折磨过。前端经常抱怨后端给的接⼝⽂档与实际情况不⼀致。后端⼜觉得编写及维护接⼝⽂档会耗费不少精⼒，经常来不及更新。其实⽆论是前端调⽤后端，还是后端调⽤后端，都期望有⼀个好的接⼝⽂档。但是这个接⼝⽂档对于程序员来说，就跟注释⼀样，经常会抱怨别⼈写的代码没有写注释，然⽽⾃⼰写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范⼤家是不够的，随着时间推移，版本迭代，接⼝⽂档往往很容易就跟不上代码了。发现了痛点就要去解决⽅案。解决⽅案⽤的⼈多了，就成了标准的规范，这就是Swag
ger的由来。通过这套规范，你只需要按照它的规范去定义接⼝及接⼝相关的信息。再通过Swagger衍⽣出来的⼀系列项⽬和⼯具，就可以做到⽣成各种格式的接⼝⽂档，⽣成多种语⾔的客户端和服务端的代码，以及在线接⼝调试页⾯等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述⽂件，就可以⾃动⽣成接⼝⽂档和客户端服务端代码，做到调⽤端代码、服务端代码以及接⼝⽂档的⼀致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述⽂件，本⾝也是有⼀定负担的⼯作，特别是在后⾯持续迭代开发的时候，往往会忽略更新这个描述⽂件，直接更改代码。久⽽久之，这个描述⽂件也和实际项⽬渐⾏渐远，基于该描述⽂件⽣成的接⼝⽂档也失去了参考意义。所以作为Java届服务端的⼤⼀统框架Spring，迅速将Swagger规范纳⼊⾃⾝的标准，建⽴了Spring-swagger项⽬，后⾯改成了现在的Springfox。通过在项⽬中引⼊Springfox，可以扫描相关的代码，⽣成该描述⽂件，进⽽⽣成与代码⼀致的接⼝⽂档和客户端代码。这种通过代码⽣成接⼝⽂档的形式，在后⾯需求持续迭代的项⽬中，显得尤为重要和⾼效。
1.说明
现在SWAGGER官⽹主要提供了⼏种开源⼯具，提供相应的功能。可以通过配置甚⾄是修改源码以达到你想要的效果。
wagger Codegen: 通过Codegen 可以将描述⽂件⽣成html格式和cwiki形式的接⼝⽂档，同时也能⽣成多钟语⾔的服务端和客户端的代码。⽀持通过jar包，docker，node等⽅式在本地化执⾏⽣成。也可以在后⾯的Swagger Editor中在线⽣成。
Swagger UI：提供了⼀个可视化的UI页⾯展⽰描述⽂件。接⼝的调⽤⽅、测试、项⽬经理等都可以在该页⾯中对相关接⼝进⾏查阅和做⼀些简单的接⼝请求。该项⽬⽀持在线导⼊描述⽂件和本地部署UI项⽬。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述⽂件的编辑器，该编辑⽀持实时预览描述⽂件的更新效果。也提供了在线编辑器和本地部署编辑器两种⽅式。
Swagger Inspector: 感觉和postman差不多，是⼀个可以对接⼝进⾏测试的在线版的postman。⽐在S
wagger UI⾥⾯做接⼝请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub：集成了上⾯所有项⽬的各个功能，你可以以项⽬和版本为单位，将你的描述⽂件上传到Swagger Hub中。在Swagger
Hub中可以完成上⾯项⽬的所有⼯作，需要注册账号，分免费版和收费版。
PS：
Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项⽬的项⽬代码，⾃动⽣成JSON格式的描述⽂件。本⾝不是属于Swagger官⽹提供的，在这⾥列出来做个说明，⽅便后⾯作⼀个使⽤的展开。
2.基于Spring框架的Swagger流程应⽤
这⾥不会介绍Swagger的⼯具具体如何使⽤，不会讲yml或者json格式描述⽂件的语法规范，也不会讲如何在SpringMVC或者Spring Boot中配置Springfox－swagger。这些都能从⽹上到，⽽且配置起来都⾮常的简单。
这⾥想讲的是如何结合现有的⼯具和功能，设计⼀个流程，去保证⼀个项⽬从开始开发到后⾯持续迭代的时候，以最⼩代价去维护代码、接⼝⽂档以及Swagger描述⽂件。
2.1 项⽬开始阶段
⼀般来说，接⼝⽂档都是由服务端来编写的。在项⽬开发阶段的时候，服务端开发可以视情况来决定是直接编写服务端调⽤层代码，还是写Swagger描述⽂件。建议是如果项⽬启动阶段，就已经搭好了后台框架，那可以直接编写服务端被调⽤层的代码（即controller及其⼊参出参对象），然后通过Springfox－swagger ⽣成swagger json描述⽂件。如果项⽬启动阶段并没有相关后台框架，⽽前端对接⼝⽂档追得紧，那就建议先编写swagger描述⽂件，通过该描述⽂件⽣成接⼝⽂档。后续后台框架搭好了，也可以⽣成相关的服务端代码。
2.1 项⽬迭代阶段
到这个阶段，事情就简单很多了。后续后台⼈员，⽆需关注Swagger描述⽂件和接⼝⽂档，有需求变更导致接⼝变化，直接写代码就好了。把调⽤层的代码做个修改，然后⽣成新的描述⽂件和接⼝⽂档后，给到前端即可。真正做到了⼀劳永逸。
2.3流程
总结⼀下就是通过下⾯这两种流程中的⼀种，可以做到代码和接⼝⽂档的⼀致性，服务端开发再也不⽤花费精⼒去维护接⼝⽂档。
流程⼀

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。