初窥 RAP:如何使用RAP进行接口文档管理

Jason 岂安科技前端研发工程师

三年互联网前端开发经验,曾参与过多个系统框架的搭建和组件开发,负责岂安科技产品的数据可视化和公用组件开发。

1 前言

RAP 是一个可视化接口管理工具, 通过分析接口结构,动态生成模拟数据,校验真实接口正确性,围绕接口定义,通过一系列自动化工具提升我们的协作效率。 在 RAP 中,您可定义接口的 URL、请求和响应细节格式等等。通过分析这些数据,RAP 提供 MOCK 服务、测试服务等自动化工具。

2 为什么要选择 RAP?

轻松编辑和分享

可视化编辑,完善的版本控制,各种格式的导入导出。让前后端约定接口的工作变得十分简单。

Mock服务

RAP会自动根据接口文档生成Mock接口,这些接口会自动生成模拟数据,并支持复杂的生成逻辑。

实力的保障

覆盖阿里几乎所有部门,有数百家公司正在使用RAP,历经4年积累大量经验,可适应各种复杂的业务场景。

3 开始 RAP

1轻松编辑和分享

要求环境: ✦ JDK 1.8+ ✦ MySql 5.6.12+ ✦ Tomcat 8.*+ ✦ Redis 3.0+

RAP的部署方式有两种: 一种是直接采用阿里编译好的 war 包,放入 tomcat 即可。 另一种是获取源码后自己编译,或者修改一些代码、做一些个性化的功能之后编译,然后打成 war 包再放入 tomcat。 具体搭建方法参考官方文档: https://github.com/thx/RAP/wiki/deploymanualcn

2注册 RAP 账号,创建团队和项目

部署到自己服务器上之后,先注册账号后登录,然后创建团队和项目。

bigsec

创建之后可以修改项目和添加项目成员,项目成员可以访问该项目的内容和添加修改接口。

3编写接口文档

登录账号后在首页,可以看到“我的项目”,选择一个项目点击进入,就可以开始编写我们的接口文档了。 进入页面后点击编辑,可以看到如下界面:

bigsec

我们可以将我们的接口文档写在这个地方,备注中可以写出模拟的数据格式,具体规则参考官网用户手册: https://github.com/thx/RAP/wiki/usermanualcn 我们可以定义接口返回固定的字符串、返回随机数,甚至定义方法根据传参做一些处理之后再返回。

4使用接口

一直看到这里,大家可能有疑问,这个文档写出来,好像和普通的文档没有什么区别啊,甚至更加繁琐。这里我们就要说到RAP与其他文档不同的地方: 写完文档之后,我们可以直接调用接口来返回数据,这些数据是根据我们编写的规则动态生成的,前端不需要等到后台开发好接口之后再调用,而是可以和后台同步开发 。 我们来看看返回的数据吧:

bigsec

这里可以模拟请求来看返回的数据是否是自己想要的结果,确定没有问题之后,我们就可以使用该接口了。因为后台工具暂时还不成熟,所以该处我们介绍一下前端如何使用该接口:

✫ 前端调用接口时,host 和 url 与平常调用有所不同,如上图,请求的 url 为右下方的 url(并始终为 get 请求,无论接口是 post 还是其他的 method),而返回的内容也并不是返回的对象,而是文档转换成的一串字符串。

✫ 在这里我们需要安装 mockjs,用于解析接口返回的内容(安装方法参考: https://github.com/nuysoft/Mock/wiki/Getting-Started)

✫ 拿到接口返回的内容后,使用 const result = eval((${res})) ; 解析返回内容,而不是使用 JSON.parse,原因是文档中编写的内容可能有 function,不能使用 JSON.parse 去转换。解析完成后使用 const data = mockjs.mock(result) ; 这时候变量 data 就是我们需要的数据了,也就是图中所返回的结果。

✫ 通过上面三步,我们就可以拿到数据去写我们的代码了。

4结束语

RAP 的基础用法,看完上面的内容我们可以了解的差不多了,缺点也比较明显,调用接口时比较麻烦,但是我们可以通过封装请求方法来减少麻烦程度。总的来说 RAP 平台还是比较实用的。

目前RAP1已经停止更新,官方开始推行 RAP2,界面更加简洁易用,但是没有什么文档,大部分文档还是使用的 RAP1 的文档(也就是今天我们介绍的 RAP 平台)。

RAP的介绍,到这里也就告一段落了,如果大家比较感兴趣可以去官方部署的 RAP 平台(http://rap.taobao.org/org/index.do)用用看,所有功能和自己部署的是一模一样的,大家可以先用用看,如果觉得还不错,就可以部署在自己的服务器上使用了。