试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档？

前言：

一般写完代码之后，还要将各类参数注解写入 API 文档，方便后续进行对接和测试，这个过程通常都很麻烦，如果有工具可以读取代码注释直接生成 API 文档的话，那会十分方便。 此前一直都是在使用 eolinker 的，但自从去年他们家“注释生成文档”的功能下线后，我就一直活在水深火热当中——真的不想写文档啊，真的好累啊。 然而这两天上线后，突然发现这个功能重新上线了！必须给大家安利一波！ 官网地址：https://www.eolinker.com 根据官方的解释，这个功能简单来说就是读取 gitlab （以前应该还能读本地代码） 的 php 代码（截至发文增加支持读取 java，更方便了）注释生成 API 文档。

下面是官方的操作介绍：

1.先在 EOLINKER 新建项目，随后进入项目概况页，可以在概况页中找到“扫描代码注解生成文档”模块。

2.在同步之前我们打开设置看下需要填写什么信息。

总共是 10 个选项，我们来分别看下需要怎么填写：

• 1.代码仓库类型，现在默认只有 gitlab，在官方群问了他们的 PM，后面应该还会支持 github。
• 2.代码仓库地址，gitlab 有线上版本和用户自己搭建私有云版本，线上版本可以填写 https://gitlab.com ，如果是自己部署的 gitlab 写域名或者 IP 端口。
• 3.项目 ID，gitlab 中新建项目后会有一个 project ID，填入即可。
• 4.访问私钥，通过 gitlab 的 Access Tokens 功能可获取，后面会详细介绍如何获取。
• 5.需要扫描的分支，默认为 master。我们也可以新建一个分支。
• 6.需要扫描的 API 目录路径，建立一个目录作为 API 目录。
• 7.需要扫描的数据结构目录路径，建立一个目录作为数据结构目录。
• 8.目标语言，目前默认只有 PHP，比较可惜只有一个语言，不过我跟他们客服聊天，说是后面更新的语言支持会增加 java。
• 9.注解格式，默认为 Swagger 2.0，代码注释编写的格式可以按照下面的形式来写，或者参考官方文档 http://zircote.com/swagger-php/annotations.html

比如 model 的

比如 controller 的

• 10.数据同步方式，目前可选增量更新、全量更新、仅添加新的 API 三种形式。以上就是需要填写的全部信息。要正确填写这些信息，接下来我们就要转到 gitlab 进行设置。

由于官方没有介绍过 Gitlab，那还是由我先介绍下比较合适：gitLab 是一个用于仓库管理系统的开源项目，使用 git 作为代码管理工具，并在此基础上搭建起来的 web 服务。gitlab 跟 github 有点类似，都是基于 web 的 git 仓库，关于注册 gitlab 新建账号如何操作的部分我就不多说了，但如果你已经有 github 账号的话，是可以用 github 账号登录 gitLab 的。

1.首先要新建项目，这里我新建了一个名为 demo code 的 project。

2.新建后已经有一个 master 的分支，然后在分支下分别建立两个新的目录：我命名为 controllers 和 models，一个作为 API 目录路径，一个作为数据结构目录路径。

3.将写好的 php 代码上传至分别的目录。可以直接用命令行或者直接将文件上传。

4.成功上传代码后，跟着就是获取密钥。在 gitlab 中，生成密钥需要用到 Access Tokens 功能。先进入设置页面，通过左边菜单中的 Access Tokens 功能，填写对应的项目名称，再根据需要，勾选开放的权限，看不懂也可以按照我下面的截图进行勾选，点击绿框后就可以获取个人的密钥了。如下图：

5.进行到这一步，我们已经把所有的信息都拿到了，再回到 EOLINKER 将信息填入，请看下图，注意数据同步方式我选择的是增量更新。

那我为什么会选择增量更新呢？而三种数据同步更新区别是什么呢？

• 增量更新：判断已有 API 的详细信息，添加新的 API 信息。用注解的数据替换掉现有的数据。部分注解没有的数据，比如 mock、参数值可能性、详细文档等等，均会保留。
• 全量更新：在添加新的 API 的基础上，全量替换现有 API 内的信息，以注解的为准，不保留注解没有的数据。
• 仅添加新的 API：判断接口名称是否已经存在，不存在则插入。 听起来很绕，我们来举个例子。Gitlab 上的接口只有参数，而导入 EOLINKER 后会有 mock、详细文档等数据。假如现在你的 gitlab 仓库有 ABCD 四个接口数据，在 EOLINKER 有 A 一个接口数据。

下面举个例子介绍下三种数据同步更新的区别，GitLab 中的接口只有参数，而导入 EOLINKER 后会有 mock、详细文档等数据。假如现在你的 GitLab 仓库有 ABCD 四个接口，在 EOLINKER 有 A 一个接口。

• 采用“增量更新”后，EOLINKER 上将新增 BCD 三个接口；如果仓库 A 接口的数据有所更新，那么在保持原有本地 A 接口的 mock、详细文档数据的同时，本地亦将新增相应更新的数据；
• 采用“全量更新”后，EOLINKER 上将有 ABCD 四个接口；此时本地 A 接口所有数据都不保留，而会与仓库中 A 接口的数据保持一致；
• 采用“仅添加新的 API ”后，EOLINKER 将以接口名称来判断是否需要添加新的 API，因此 EOLINKER 上将新增 BCD 三个接口；即便 GitLab 上的参数已经改变，但本地原有的 A 接口数据不变；

因此，无论是什么情况都推荐采用增量更新。不过即便你还是误操作了，EOLINKER 都会自动生成 API 历史版本，方便我们回滚文档，操作失误也不怕了。

1.根据官方的说明，在设置完成点击立即同步后，文档即会开始进行同步，而同步生成文档所需的时间，则根据代码注释的数据量来决定。

2.API 文档和对应的分组都被自动生成了，如下图。

3.那我们就可以直接编辑修改文档了，实在是方便了很多。

补充一句：按照他们的更新速度，目前也已经支持读取 gitlab 上 java 代码了，操作步骤跟读取 php 的步骤类似，这里就不展开说了，还不知道请回头再看一遍文章 hhh。

总结

如果可以通过扫描代码注释自动生成 API 文档，写完代码注解后就不用再一条一条的写接口文档，现在又有一个理由可以不再使用 swagger 了。新增的这个功能可以减轻大部分不必要的工作量，虽然现在只能支持 gitlab 上的 php 代码和 java 代码，但后续肯定还会继续支持更多的平台和编程语言代码，持续使用起来将会更加方便和快捷，希望 eolinker 能够给我们带来更多的惊喜。官网地址：https://www.eolinker.com