一般写完代码之后,还要将各类参数注解写入 API 文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成 API 文档的话,那会十分方便。 此前一直都是在使用 eolinker 的,但自从去年他们家“注释生成文档”的功能下线后,我就一直活在水深火热当中——真的不想写文档啊,真的好累啊。 然而这两天上线后,突然发现这个功能重新上线了!必须给大家安利一波! 官网地址:https://www.eolinker.com 根据官方的解释,这个功能简单来说就是读取 gitlab (以前应该还能读本地代码) 的 php 代码(截至发文增加支持读取 java,更方便了)注释生成 API 文档。
下面是官方的操作介绍:
总共是 10 个选项,我们来分别看下需要怎么填写:
比如 model 的
比如 controller 的
由于官方没有介绍过 Gitlab,那还是由我先介绍下比较合适:gitLab 是一个用于仓库管理系统的开源项目,使用 git 作为代码管理工具,并在此基础上搭建起来的 web 服务。gitlab 跟 github 有点类似,都是基于 web 的 git 仓库,关于注册 gitlab 新建账号如何操作的部分我就不多说了,但如果你已经有 github 账号的话,是可以用 github 账号登录 gitLab 的。
那我为什么会选择增量更新呢?而三种数据同步更新区别是什么呢?
下面举个例子介绍下三种数据同步更新的区别,GitLab 中的接口只有参数,而导入 EOLINKER 后会有 mock、详细文档等数据。假如现在你的 GitLab 仓库有 ABCD 四个接口,在 EOLINKER 有 A 一个接口。
因此,无论是什么情况都推荐采用增量更新。不过即便你还是误操作了,EOLINKER 都会自动生成 API 历史版本,方便我们回滚文档,操作失误也不怕了。
补充一句:按照他们的更新速度,目前也已经支持读取 gitlab 上 java 代码了,操作步骤跟读取 php 的步骤类似,这里就不展开说了,还不知道请回头再看一遍文章 hhh。
如果可以通过扫描代码注释自动生成 API 文档,写完代码注解后就不用再一条一条的写接口文档,现在又有一个理由可以不再使用 swagger 了。新增的这个功能可以减轻大部分不必要的工作量,虽然现在只能支持 gitlab 上的 php 代码和 java 代码,但后续肯定还会继续支持更多的平台和编程语言代码,持续使用起来将会更加方便和快捷,希望 eolinker 能够给我们带来更多的惊喜。官网地址:https://www.eolinker.com
1
6IbA2bj5ip3tK49j 2019-03-26 12:06:09 +08:00 4
最烦这种官方软文。本质就是欺骗。
假装自己是用户,还问了他们 PM,假装个毛啊,直接说我们上了 XXX 新功能不就完了吗。 |
2
muxuClover OP @xgfan 他们 上了扫描代码注释自动生成 API 文档功能
|