初窥 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/deploy_manual_cn

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

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

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

3编写接口文档

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

进入页面后点击编辑，可以看到如下界面：

我们可以将我们的接口文档写在这个地方，备注中可以写出模拟的数据格式，具体规则参考官网用户手册：

https://github.com/thx/RAP/wiki/user_manual_cn

我们可以定义接口返回固定的字符串、返回随机数，甚至定义方法根据传参做一些处理之后再返回。

4使用接口

一直看到这里，大家可能有疑问，这个文档写出来，好像和普通的文档没有什么区别啊，甚至更加繁琐。这里我们就要说到RAP与其他文档不同的地方：

写完文档之后，我们可以直接调用接口来返回数据，这些数据是根据我们编写的规则动态生成的，前端不需要等到后台开发好接口之后再调用，而是可以和后台同步开发 。

我们来看看返回的数据吧：

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

✫ 前端调用接口时，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）用用看，所有功能和自己部署的是一模一样的，大家可以先用用看，如果觉得还不错，就可以部署在自己的服务器上使用了。