V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
muxuClover
V2EX  ›  程序员

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

  •  
  •   muxuClover · 2019-03-26 11:58:35 +08:00 · 1313 次点击
    这是一个创建于 2071 天前的主题,其中的信息可能已经有所发展或是发生改变。

    前言:

    一般写完代码之后,还要将各类参数注解写入 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 一个接口数据。

    下面举个例子介绍下三种数据同步更新的区别,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

    2 条回复    2019-03-29 17:51:20 +08:00
    6IbA2bj5ip3tK49j
        1
    6IbA2bj5ip3tK49j  
       2019-03-26 12:06:09 +08:00   ❤️ 4
    最烦这种官方软文。本质就是欺骗。
    假装自己是用户,还问了他们 PM,假装个毛啊,直接说我们上了 XXX 新功能不就完了吗。
    muxuClover
        2
    muxuClover  
    OP
       2019-03-29 17:51:20 +08:00
    @xgfan 他们 上了扫描代码注释自动生成 API 文档功能
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1359 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 17:38 · PVG 01:38 · LAX 09:38 · JFK 12:38
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.