如何使用 EOLINKER 扫描代码注释生成 API 文档？

EOLINKER API Studio 5.0.4 版本已于近期更新，本次更新中新增大家期盼已久的功能—-支持读取 GitLab 的 php 代码注释生成 API 文档。通过该功能，使用者不用再手动撰写 API 文档，极大的减轻了开发工作量。EOLINKER 将通过下面的引导，为大家介绍如何使用 EOLINKER 快速读取 GitLab 代码注释，并自动生成 API 文档。

1.为了方便演示，先在 EOLINKER API Studio 中新建项目，将其命名为 gitlab php code。新建项目后，进入项目概况页，在概况页中可以快速找到“扫描代码注解生成文档”模块。

2.同步之前打开 设置 选项，将相应 GitLab 项目的内容填写完整。

总共是10个选项，分别需要填写的内容是：

代码仓库类型：目前默认只有 GitLab，后续更新会增加支持 Github； 代码仓库地址：GitLab 有线上版本和用户自己搭建私有云版本，线上版本可以填写 https://gitlab.com，如果是自己部署的 GitLab 则写域名或者IP端口； 项目 ID：GitLab中新建项目会有一个 project ID，填入即可； 访问私钥：通过 GitLab的 Access Tokens 功能可获取，后面会详细介绍如何获取； 需要扫描的分支：默认为 master。我们也可以新建一个分支； 需要扫描的 API 目录路径：建立一个目录作为 API 目录； 需要扫描的数据结构目录路径：建立一个目录作为数据结构目录； 目标语言：目前默认只有 PHP，后续更新会增加支持 java； 注解格式：默认为 Swagger 2.0，代码注释编写的格式参考下面的形式来写，或者参考官方文档http://zircote.com/swagger-php/annotations.html 数据同步方式：目前可选增量更新、全量更新、仅添加新的 API 三种形式；（关于三者的区别，在后文会举例说明）

如不清楚从哪里获取以上信息，请转到 GitLab 进行设置。

下面举个例子介绍下三种数据同步更新的区别， 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 历史版本，方便回滚文档，即便操作失误也不用担心。

3.设置完成后，点击立即同步，同步生成文档需要的时间根据代码注释的数据量来决定。

4.API文档和对应的分组信息完整生成，方便直接编辑文档。

从2018年年中下线的“根据代码注释自动生成API文档”功能，经过改版后重新上线，目前仅支持读取GitLab上的PHP代码，EOLINKER将在后续更新的版本中支持更多的代码仓库和格式语言，我们将持续为大家提供高效、专业、安全的接口管理服务。