试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档?
发布于 1 个月前 作者 wardennn 476 次浏览 来自 分享

前言:

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

下面是官方的操作介绍:

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

图1概况页功能.png

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

图2同步需要填写的信息.png

总共是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的

代码截图.png

比如controller的

代码截图2.png

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

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

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

图3新建项目.png

图4新建demo.png

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

图5在master下建立目录.png

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

图6上传php代码.png

图7三个php代码.png

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

图8获取个人密钥.png

图9个人密钥.png

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

图10信息设置.png

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

  • 增量更新:判断已有API的详细信息,添加新的API信息。用注解的数据替换掉现有的数据。部分注解没有的数据,比如mock、参数值可能性、详细文档等等,均会保留。
  • 全量更新:在添加新的API的基础上,全量替换现有API内的信息,以注解的为准,不保留注解没有的数据。
  • 仅添加新的API:判断接口名称是否已经存在,不存在则插入。

下面举个例子介绍下三种数据同步更新的区别, 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.根据官方的说明,在设置完成点击立即同步后,文档即会开始进行同步,而同步生成文档所需的时间,则根据代码注释的数据量来决定。

图11点击立即同步.png

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

图12API文档和分组被自动生成.png

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

图13编辑文档.png

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

总结

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

回到顶部