Eolink征文活动---Eolink API文档服务的天才产品

实际上我并不是因为这次活动才知道Eolink，早在几年前，我就成为了Eolink的使用者，所以，这次征文活动我势在必行！本篇文章将会围绕我如何利用Eolink去解决项目问题进行展开讨论，大致分为以下内容：

我为什么选择Eolink？
Eolink解决了我的哪些问题？
我对Eolink的小建议

选择Eolink的原因

因为本人所在单位主要是做企业数字化服务，所以会存在很多个项目统一管理的问题，而API文档作为研发、测试、前端的连接工具，更是显得尤为重要。我的需要这个文档解决的问题就是：

他必须标准化，不标准化就会带来文档差异，导致阅读成本大幅提升，并且直接影响到沟通效率
对于以前建立的一些文档，必须能够支持无缝迁移过来，不然老项目的文档需要重新写一遍进行管理
有时候需要提供给第三方一些接口，但是并不会完全将整个项目共享，这种情况可以有两种解决办法
- 文档自带权限控制，可以部分共享
- 可以将已管理的部分文档导出给第三方，并且转换成第三方所需的格式
文档最好是能够将人员的相关信息记录清楚，在对接API时可以有效联系到相关人员
希望文档系统能够支持其他系统的对接，例如一些研发完成事件，能提供一些Hook，及时推送给钉钉或者企业微信等

根据我的问题场景，我总结一下文档系统需要满足的条件：高度规范化、可读性高、易维护性强、可移植性强、权限可控，并且最好是可以连接其他系统，达到流程自动化。针对上述需求，我也开始了文档系统的调研工作，以下为个人调研结论

类型	文档工具	已满足	未满足
基于注释生成文档	swagger、smartdoc	标准化、可读性一般、维护性一般、高效	文档描述有限、无权限控制、无法对接第三方
自定义标准化文档	showdoc	自定义标准化，需要花费较高成本去维护，可读性可维护性直接自己把控、权限控制	无法对接第三方，文档好坏自己定义
第三方文档服务	eolink	高度规范化、可读性高、易维护性强、多种导入方式、权限控制、支持第三方扩展	对于连接其他系统，这边也相当于是实现了，但是没有达到我的预期

综合我的需求，我们最终选择了Eolink作为文档管理系统，有几点主要原因，我们需要高度规范化，对于那些自定义标准化还有对代码入侵比较高的注释生成文档，我们基本上是不怎么考虑的，期间我们也考虑过yapi，但是在之前的一段时间 yapi 出现的了远程命令执行漏洞，这也让我们一直坚持使用专业的文档服务，避免成本与安全上的失衡。

可以看到我使用Eolink也快两年了，还是有一定使用经验，接下来，我将把我遇到的问题如何应用Eolink解决分享给大家！

Eolink解决的问题

以前写的API文档怎么办？

这个问题不用担心，作为一个高级的文档服务平台，支持大多数文档的迁移，如果你是以下几种文档，可以无缝迁移过来:

eolink 同平台，不同账号
postman
jemeter
swagger
yapi
apidoc
apipost
apifox
HAR
RAP
…

可以看到，主流的文档平台都是支持无缝对接的，并且你在postman、apipost中发起的请求测试，都可以直接导入，因为我们之前有些项目使用 swagger 进行文档编写的，所以我这边将历史文档都统一迁移到 eolink中了，迁移过程如下：

首先访问swagger地址

然后请求json文档地址，选择ctrl+s另存为

直接导入http.json

可以看到，很快就导入成功了，预览了一下，效果确实不错

API没开发完，前端要测试对接怎么办？

实际上API的主要目的就是为了连接客户端和服务端，当产品经理给出需求后，前后端就会预先沟通好API对接情况，我单位主要是前后端讨论后，由前端给出所需数据字段，后端研发好服务后组合服务满足前端需求，但在这个流程后端往往不能及时地给到前端已经研发好的API，针对这种情况，我一般都会采用Mock数据进行解决，但是在前端Mock时，我们就发现，Mock与代码有一定耦合度，并且Mock的数据只能由前端人员修改，其他人员无法参与并协同工作，还有就是请求实际并未真实发送，只是被本地拦截了模拟响应…

Eolink的Mock很有意思，我认为是一个亮点，它可以让你每一个创建的API都定制高级Mock，他会自己创建一个测试的URL地址，然后让你去定制请求参数以及响应数据，可以让你真实的去请求地址，并且通过一定规则生成的数据真实性也比较高，如下所示:

可以看到，Eolink很细节的一个地方，他的Mock既可以让你跟随响应变化，也可以让你自己去定义JSON，这种Mock服务接口可以有效的同步多方信息，前端无需感知是否Mock，并且还可以通过界面修改Mock数据，而测试也可以利用建立好的Mock提前建立好单元测试，不用等到API完全出完再进行编写，提升工作进度，并且这种中心化管理的方式，Mock一旦修改，多方自动同步，非常省事放心。

API如何保证正确性

Eollink有个自动化测试，通过在平台上建立API自动化测试用例，然后通过代码提交Hook，然后集成Jenkins，实现提交即自动测试并获取测试报告，这一点也是后面发现才用上，真的很香。

为什么我会考虑使用Eolink这个自动化测试，我们的项目在进行回归测试时，还没有达到完全自动化测试的程度，导致我们测试的效率低，覆盖面不够广，有时候还会遗忘掉一些，并且上线一般都在大半夜，上完线然后测试需要很长时间也会导致团队整体上线效率降低，并且各个测试也需要同步测试用例，测试之前也需要协作，所以Eolink的出现可以说是救我于水火之中了。

首先先添加一个测试流程，这里主要是你的业务流程

添加完业务测试用例后，需要将过程组织起来，这里我们可以考虑之前写好的api直接导入过来

可以看到，这里我直接导入了登录API和查询积分余额接口作为本次用例的过程，接下来就是开始测试了，要注意，一般流程协作都涉及到数据传递，所以我们会提取上一个接口的数据作为下一个接入的请求参数，如：这边我需要获取登录响应的token带到获取积分余额中去

Eolink的API自动化测试可以设置定时任务，实现项目在无人值守的情况下自动测试并且发送报告给相应的邮箱，监控项目监控情况。

如何及时感知API的健康问题

如果还没有自己的健康检查服务的可以考虑使用Eolink来做，很全面，并且有可视化监控界面，可以保证API出现异常及时反馈，通知给负责人，特别是对于核心的API，因为核心API一旦出现问题，就意味着整个程序的流程都会中断，价值是以每秒进行递减的，损失少则几十万，重则几百万，以下为我项目中的监控示例：

首先可以先添加一个API作为监控，这个API可以是之前文档的导入，也可以是自己新增的

然后我们对API开启监控功能

进入监控后，可以看到每个步骤的处理延时情况

整个的数据大盘表现如下

并且在监控日志中还可以看到错误报告

我对Eolink的小建议

实际上，Eolink已经非常的成熟可靠了，但是我作为使用者，肯定是还会有一些个人的小习惯，基于我使用过的一些产品，我在此也提出一些小小的建议，希望Eolink官方可以根据合理性进行采纳或者通过其他方式进行产品优化，作为一个使用接近两年的用户，还是希望Eolink能够蒸蒸日上，产品服务越做越好。以下是我的个人建议：

我认为每个模块的侧边栏上应该加上对应模块的使用文档，让新接触的用户能够第一时间了解并使用产品，最好是以小窗口方式打开，类型阿里云、腾讯云是做的还可以的，因为我在给内部做推广的过程中，他们需要专门去文档中心查看，或造成一些时间成本的浪费
希望目录/分组可以支持前置/后置脚本，因为数量一旦多了就无法高效查找了
能否有一个数据中心，各个板块的一些核心数据能够一目了然那种，不需要单独进入每个板块查看，只要核心数据就好了，这样我可以针对数据结果然后再去优先查看数据不稳定的板