Eolink 征文活动- -后端研发需要的API文档工具

Eolink功能太多，一两篇文章聊不完，这篇文章只是聊聊Eolink的API文档管理功能。

首先大致说说我所认知的API文档工具历史。

我所知的API文档工具历史

我是2010年左右参与工作的，作为一个十来年工作经验的Java后端研发工程师，对API文档工具真的是百感交集。

2010年左右的阶段

刚入行的时候API文档是word文档记录的，包括版本号和改进内容，存储在个人电脑、CVS、SVN。

那时候的研发流程是技术方案通过后先写word的API文档，和前端稍为碰了一下接口的内容后便开始写代码（前端开始切图写页面），接口自测用chrome浏览器的postman插件（当然还有curl之类的硬核一点的自测方式），前后端测试之间的交流就是通过IM工具发word文档，改word文档。这已经是当时后端研发流程最快的配套。

但是很多时候每个人的个人PC电脑的word版本都不大一致，特别是写API word文档的人离职后，一般就只剩下代码是最新的，api文档有复数个版本，没有一个是最新的，假设这个时候出现了关于这个api的线上问题，就会一地鸡毛。

这个阶段带来的问题就是写API文档非常耗时、跨组/部门沟通麻烦、自测麻烦、迭代一段时间后版本混乱。那时候一个好的API文档甚至可以让人感叹素质之高堪比IBM员工（当时IBM所有类型的研发文档都是业界标杆）。

那个时候流行接口协议还是比较单一，普遍是http1.0。对于java从业者来说，业界正在开展SSH、SSM、Play等等框架大乱战，这给写API文档增加了负担和难度，甚至埋下了很多坑。

2015年左右的阶段

15年左右国内出现了一批国外小有名气的工具，譬如apidoc、swagger等等。那时候这类型的工具一般还是在优化写API文档的效率，不过有些也提供了测试功能。

这些工具一般是通过2个方向来进行操作提升的。
第一种是自定义注释，代码非侵入式的，通过部署第三方进程扫描代码生成api文档。成本在于后端需要学习第三方工具的注释，学习部署第三方工具进程和应用，好处就是api文档能自动生成了，并且是研发业务逻辑代码之前生成api文档（定义好接口写好注释就能生成）。

第二种是自定义注解，代码侵入式的，项目需要引入第三方框架的jar包，通过运行项目代码的时候自动生成api文档。成本在于后端需要学习第三方工具的注解，学习部署第三方工具应用，好处也是api文档能自动生成了，但是往往要项目能跑的时候才有api文档，就是前端和测试拿到api文档的速度相对第一种方式来说会比较慢，而且有个比较让人介意的点，这类型的工具是侵入式的，一般重要的项目都不会使用侵入式的工具，担心安全和性能问题。

这个时候根据不同场景使用不同工具确实使后端写API文档的效率提升了，API版本混乱也好了些，但是该有的协调问题，多工具之间的API版本混乱问题还是有的，基本上就是造福了后端研发，也引入了学习成本的新问题。然而这个时候流行的接口协议开始多了起来，thrift、protocol、dubbo等等，新流行的工具并没有完全兼容这些开始流行的协议接口，后端研发的有些API文档又开始了10年那个阶段的刀耕火种（甚至有一直停留在刀耕火种阶段的公司），并且让前端和测试能力被动升级，毕竟对接、测试http协议和dubbo的协议难度不可同日而语。

2020年左右的阶段

20年左右国内一些造轮子能力强的公司已经在IDE上研发出了一键生成API文档的功能，无论是啥协议，都一键生成。这种玩法结合了15年阶段了2个方向，并且扩展了多种协议，独立部署的进程融进了IDE，并且是代码非侵入式的，成本依然是需要学习公司内部自定义的注释（当然，不写注释自动生成也行，比较考验方法函数和对象属性的英文命名的遣词能力），这至今也是后端最省事的API文档生成工具，注释和文档只要写一种就行了，甚至都可以不写。

那时候很多第三方的API工具都比较出名了，都能从各个方面做到降本增效，但是都是比较独立的，独立便意味着协同沟通问题并没有解决，不同工具之间同一个api版本不一样的问题也没解决。这个时候开始出现了些SaaS产品解决了独立的问题，Eolink便是其中之一，并且已经在这一行深耕积累了3年多。

在20年这些工具主要解决的问题还是协同问题，说白点就是沟通问题。他们搭建了一个服务器，大家将api文档都在服务器上维护，这样版本管理和沟通都方便了一个等级。看起来这就是API文档工具的未来，其实暂时还不是，准确些说是还不能够。

因为这个时候流行的通信协议更多了，甚至还多了亟待需要规范测试的消息队列通信协议，http甚至连3.0都开始有公司在实践了。当时的SaaS工具并不能满足所有协议，甚至到2022年的当下的也不能。

那个时候相关API工具已经迭代至少10年了，从深度来说也没解决所有问题。这些问题绝对不是一个迭代了3、4年的产品能完全解决的，更别说更年轻的产品。这类型的SaaS工具一般是解决了被大部分公司共同诟病的问题——Http接口协议的沉淀管理和协同。

站在当下看来，老牌的第三方工具深度解决了些API文档问题，但是却没办法解决协同问题，因为大部分都是单点的工具，并无法打通。而SaaS产品从广度解决了协同管理的问题，但是深度问题有待加强，但是只要能将各个功能点深度迭代下去就能将老牌工具淘汰掉。作为一个后端研发，只能说拭目以待，当下当然是先看看这类型的产品给后端这个角色带来什么好处在说。

API文档工具解决的三大场景

啰嗦了那么久，只想归纳总结下一个作为一个研发后端对API文档工具的希冀，就是最起码能解决API文档的生成编写问题、API文档管理问题、API文档的沟通问题。再抽象总结一层是API文档工具能解决的场景包括三种——当前、过去、未来。当前就是研发过程当中如何增量新增API文档；过去就是存量的旧项目的API文档如何沉淀保存，特别是那些没有录入过API文档的代码，除了代码一无所有的旧项目；未来，业界技术不停迭代更新的未来，当下的工具如何兼容。

现在可以说回去上文消失了很久的Eolink的API文档工具了，说说它是怎么一次过满足我三个愿望的。

为啥不说说其他工具？因为单单是自动生成API文档这个功能就可以将其他产品工具劝退了，截止发文时（2022年12月9日）在所有第三方工具当中，能在IDE生成API文档的产品工具应该没一个比得过Eolink的（其他SaaS产品没这个功能，单点工具又有协同问题），都2202年了，就别再手写API文档了。

相信做后端研发的都经历过写一个超多入参出参的接口文档所花费的时间（一把20投的LOL起码是够的），特别是联调测试阶段还要修修改改，而用API生成插件能一秒生成所有API文档，这时间花费不是同一个级别的。用算法的度量来说，就是线数级别的VS常数级别的时间复杂度。

这10多年的研发经验经常让我产生些大胆又刺激的想法，譬如不写注释，譬如不写文档，譬如删库跑路，譬如sudo rm -rf *。只有一键生成API文档功能让我实现了头两个譬如。

API文档增量增加场景（当前）

众所周知，一般项目研发流程就是需求分析——》概要设计 ——》详细设计 ——》编码实现 ——》测试 ——》上线。后端研发一般都要在详细设计阶段将API文档完成，交给前端和测试并行展开之后相关的编码工作（基操，API-FIRST，也就是Eolink首创提倡的DTDD）。

当前场景就是后端研发在项目研发过程当中的详细设计阶段，这个阶段如何快速地完成API文档的编写，这个场景也可以说API文档增量增加场景。

Eolink一键生成API文档插件

我们先来看看Eolink怎么完成一键生成API文档功能是这个事情的。
首先，我们得拥有一个Eolink的SaaS账号（Eolink的私有云账号也行），这是前置。
一键生成插件的是IDEA一个插件功能（大致原理是它扫描java代码，用ATS语法树解析代码获取API文档相关的属性，再调用Eolink的新增API文档Open API，将API信息增加到Eolink上），所以我们要在IDEA的插件市场安装一个Eolink的插件（也可以在IDEA官方下载安装包后离线安装，下载链接：IDEA市场Eolink插件离线下载）。

插件安装流程如图：

安装后需要给插件配置Eolink服务器链接、项目haskkey以及个人账号信息，如图：

做好这两个步骤好插件就安装好了，写代码的时候就可以单击右键上传API上Eolink了。循例放个上传操作的截图：

上传单个java文件的API的操作流程是在java文件窗口单击右键出菜单栏，先点击Generate Class Doc，给java controller文件生成注释，然后再点Upload All Api生成上传所有api文档。（这个操作可以自定义快捷键加速）

上传后如图：

这里解释一下为什么要点击操作两次，程序实现上是可以实现点击操作一次便上传所有API文档的，但是点击一次没办法帮助研发自动生成可读性高的API接口分组命名和API名称，所以实现上分开了两次，中间生成java文件注释后给用户自己润色下分组、API的命名。

这里只是列举了一键生成上传API文档的其中一种用法——单个java文件维度API文档生成上传。其实插件也支持整个项目维度的API文档生产上传，而且还支持Dubbo协议（不过要换Eolink私有云部署才能用，SaaS版本暂时还不支持Dubbo。详细的使用教程可以访问IDEA的插件官网介绍查看，链接地址是：Eolink APIKit插件IDEA官网介绍地址

另外听闻这个插件将要开源，用户可以定制支撑自己的API文档分析生成规则，甚至可以支持一些mq的http协议的api文档生成。

理解了这个流程之后应该有人会有想法，看上去swagger、gitlab自定义插件也能完成这个事情，好像没太大差别。其实不是的，这里头涉及到一个项目组内员工工作并行时序的问题，前端和测试什么时候能用API文档展开他们的研发工作。回到上面说的项目研发流程的详细设计、API-First、DTDD等概念，swagger和gitlab插件无法方便地将api文档交给前端和测试，这两种工具都倾向于后端将代码逻辑完成后再提供API文档，当然并非绝对，但是如果要提前给API文档需要做多很多操作，过程将变得很复杂，没IDEA插件+Eolink那么方便。

其实，Eolink也支持swagger的API导入以及gitlab代码文件分析生成API接口文档，具体大家可以去自行了解。

API文档存量增加场景（过去）

存量API文档的场景主要有2种，一种是换API文档工具的场景，旧项目的API文档都要迁移。一种是旧项目，特别是远古屎山那种旧项目。真的是被生活所逼，谁会想处理上一手同事的没有文档的没有注释的代码？还要整理出API文档？

幸好，这两种场景Eolink都有比较友好的解决方案

换API文档工具

换API文档工具这种场景处理方案十分简单，见图生义：

在绿色的** +API **按钮那点击白色的倒三角形，再点击导入API就会有这个导入界面。该支持的都支持了，不该支持的也支持了。如果还有图里没有的，还记得一件生成API文档插件的实现原理吗？通过Eolink OpenApi上传。对！作为一个程序员，还可以写脚本上传。

旧项目

稍微展开说说这种场景。

正常的java项目

还记得一件生成API文档插件（这东西真的是万能）吗？这能解决一部分java老项目的问题，自动生成注释，整个项目级别的api上传，不敢说百分百无误，起码是个正常的java项目应该都没问题，实在有问题那自己写注释，API插件也支持生成上传API文档，就是工作量大了些，不过组内员工分摊分摊估计也很快。

不那么正常的项目

这里头我不得不提一句，上面说过10年的时候java框架大乱战，有些高手当初封装过一些比较流弊的control层的轮子——所有入参都是map类型，http协议的api接口灵活到没人有，无论多少入参接口都能响应，就是不知道日后维护测试心里有多少MMP。
这么久远的事情、场景你问我为啥会知道？那肯定是因为代码还能跑呀，而且没文档呀，真的是说多了都是泪。这里我再抽象总结一层，就是远古屎山，并且不正常并且没文档没注释的项目怎么办？
一般来说正常手段是解决不了不正常的项目的，所以得考虑盘外招，代码能跑就代表可以让网关生成接口日志，然后再通过网关日志生成api接口文档。Eolink用脚本来分析Nginx网关日志来生成API文档解决了这种疑难杂症的场景，不过人家的这个脚本还有一个比较流弊的功能，就是将线上的接口日志直接生成测试用例作流量回放，并且这个功能不区分编程语言，有日志就行！
这个功能是个beta版本，内测群有公告，有需要找Eolink客服应该可以提供。

API文档协议更新迭代的场景（未来）

上文有说过，业界的技术一直在更新迭代，很多新出的技术其实要立刻有工具支持是很难的，譬如devops的工具矩阵，每家公司都不大一样。
Eolink支持的协议不算少了，TCP、UDP、Websocket、Http、Dubbo、Hfs，据我所知年底就完整支持gRPC，而且Eolink有一个很好的地方就是开放了很多OpenAPI，如果工具之间有开放足够的OpenAPI就可以很友好很万能地支持其他工具的集成，这样子可以共建生态，有方向可以解决一些未来的问题，譬如现阶段可以通过OpenAPI 生成mq的http协议接口文档。

Eolink OpenApi所在位置如图：

Eolink OpenAPI列表：Eolink 线上产品 Open API

这就完了吗？是不是好像漏了什么？API文档管理问题、API文档的沟通问题好像是只字未提对吧？其实关于API文档管理的问题，只要用了Eolink就解决啦，可以理解为Eolink是一个API仓库，所有人都遵守规矩在里头放自己的API，根本不存在版本混乱的问题。而至于API文档的沟通问题，那还真的要展开说一说。

Eolink API文档管理的日常实践

API文档生成功能

这个不再多说，上文已交待得很清楚。

API文档分享功能

一般来说项目流程走到详细设计阶段，可以在IDEA那定义好接口和入参出参DTO（不需要写业务代码的实现逻辑），然后通过插件一键生成所有API文档，接着可以就会将API文档链接发给前端和测试【实际业务逻辑编码阶段之前】。

项目研发过程当中对于有权限的员工给Eolink API文档链接，没权限的跨公司的情况可以给分享链接，功能在项目管理——分享里头，分享可以设置API是局部分享或是全量分享，并且可以给跨公司场景的人提供不同的权限，譬如API测试、Mock、测试用例等等。
分享设置如图：

分享API界面如图：

API mock功能

流程到这里需要停顿下，后端可以主动谢绝所有API接口文档基础信息的沟通（譬如入参是什么、有没有返回xx属性等等），前端测试有什么需要了解的直接看API文档链接则可，并且他们可以用Eolink的api mock功能做业务逻辑确认，而mock功能可以被动谢绝大部分前端测试一段时间的沟通，这段时间的距离大概是编码完成将API放到测试环境的阶段。总之让API文档相关的沟通问题尽量通过Eolink文档自行解决。

这里头可以上图介绍下Eolink的mock功能：

API变更通知功能

当项目流程走到编码实现阶段，修改API文档可以通过IDEA的一键生成API文档来快速更新Eolink上的API文档。而此时如果前端和测试已经展开他们的工作了，他们可以通过Eolink的站内信、邮件功能获取API变更的通知，甚至可以通过配置webhook，通过企业微信、飞书等IM工具获取API变更通知（谢绝沟通+1）
接着上图：
站内信设置：

打开站内信通知界面：

而webhook的设置在刚刚的open api同样的位置那：

API 自我测试功能

编码实现阶段还可以通过快速测试功能来做api的自测。
如图：

等编码实现阶段过去了就是联调和提测了。这时候依然是围绕以Eolink的API文档为沟通就行，用公共API文档截图复现的问题结果比较容易接受，不会浪费太多个人复现时间。

OK，站在后端的角度需要什么样的API文档工具就到这一段落啦，这一套下来能为后端研发节省很多时间，可以在工作时间多喝几杯咖啡奶茶了。后续有机会再补充其他角度的工具使用文章。