EOLINKER API Studio 5.0.4 版本已于近期更新,本次更新中新增大家期盼已久的功能----支持读取 GitLab 的 php 代码注释生成 API 文档。通过该功能,使用者不用再手动撰写 API 文档,极大的减轻了开发工作量。EOLINKER 将通过下面的引导,为大家介绍如何使用 EOLINKER 快速读取 GitLab 代码注释,并自动生成 API 文档。
1.为了方便演示,先在 EOLINKER API Studio 中新建项目,将其命名为 gitlab php code。新建项目后,进入项目概况页,在概况页中可以快速找到“
扫描代码注解生成文档”模块。
[caption id="" aLIgn="aLIgncenter" widTH="1675"]
项目概况页[/caption]
2.同步之前打开
设置 选项,将相应 GitLab 项目的内容填写完整。
[caption id="" aLIgn="aLIgncenter" widTH="629"]
扫描代码注解设置[/caption]
总共是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 三种形式;(关于三者的区别,在后文会举例说明)
[caption id="" aLIgn="aLIgncenter" widTH="757"]
Swagger 2.0 格式示例:models[/caption]
如不清楚从哪里获取以上信息,请转到 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.设置完成后,点击立即同步,同步生成文档需要的时间根据代码注释的数据量来决定。
[caption id="" aLIgn="aLIgncenter" widTH="1408"]
点击立即同步[/caption]
4.API文档和对应的分组信息完整生成,方便直接编辑文档。
[caption id="" aLIgn="aLIgncenter" widTH="1500"]
API列表页面[/caption]
[caption id="" aLIgn="aLIgncenter" widTH="1500"]
API编辑页面[/caption]
从2018年年中下线的“根据代码注释自动生成API文档”功能,经过改版后重新上线,目前仅支持读取
GitLab上的
PHP代码,EOLINKER将在后续更新的版本中支持更多的代码仓库和格式语言,我们将持续为大家提供高效、专业、安全的接口管理服务。