Apikit 自学日记:自动生成 API 文档

CV_coder
224 阅读5分钟

功能入口：API管理应用 / 选中某个项目 / 其他菜单 / 数据源同步（API文档自动生成）

该功能可通过配置数据源信息，实现基于数据源的API信息自动生成API文档。

当前支持5种数据源：Swagger URL、apiDoc、Github、gitlab、码云。

Swagger URL & apiDoc 数据源

Swagger URL和apiDoc的数据源配置方式一致，仅需填写来源名称和json文件的访问地址即可。

  • 字段解析

  • 来源名称：用于标识该来源的名称，输入名称不影响同步效果。

  • json文件访问地址：Swagger URL或apiDoc生成的Json地址。注意该地址需可通过网络访问，以及该地址需可返回JSON类型的数据，否则会提示无法访问该地址。

Gitlab & github & 码云数据源

代码仓库类的数据源配置较为复杂，系统会远程读取仓库中的代码，根据Swagger 2.0的代码注解格式，自动生成对应的API文档。

  • 字段解析

  • 各代码仓库类型的数据源配置字段解析如下：

GitHub

配置项

说明

代码仓库类型

选择Github

代码仓库地址

默认填写 github.com

用户名

Github 账户名称

仓库名

Github Repository 仓库名称

访问私钥

仓库私人令牌在GitHub Repository 的Settings->Developer settings->Personal access tokens中生成

需要扫描的分支

默认为 master 分支，您也可以选择实际需要扫描的代码分支

需要扫描的 API 目录路径

API 层相关代码的存放路径

需要扫描的数据结构目录路径

数据结构相关配置信息的存放路径

目标语言

Java 或 PHP

注解格式

默认为 Swagger 2.0，代码注释编写的格式参考下面的形式来写，或者参考官方文档 github.com/zircote/swa…

数据同步方式

目前可选增量更新、全量更新、仅添加新的 API 三种形式，API 研发管理平台 推荐采用增量更新的方式。每次同步之后，系统都会自动生成 API 历史版本方便回滚文档，因此即使操作失误也不用担心。

生成API文档的默认状态

扫描得到的新增加的API的默认状态，默认是启用状态

GitLab

配置项

说明

代码仓库类型

选择Gitlab

代码仓库地址

GitLab 有线上版本和用户自己搭建私有云版本，线上版本可以填写 gitlab.com，如果是自己部署的 GitLab 则写域名或者IP端口

项目 ID

GitLab 中的 project ID

访问私钥

可以通过 GitLab 的 Access Tokens 功能获取

需要扫描的分支

默认为 master 分支，您也可以选择实际需要扫描的代码分支

需要扫描的 API 目录路径

API 层相关代码的存放路径，例如：src/main/java/com/example/demo/controller

需要扫描的数据结构目录路径

数据结构相关配置信息的存放路径，例如：src/main/java/com/example/demo/model

目标语言

Java 或 PHP

注解格式

默认为 Swagger 2.0，代码注释编写的格式参考下面的形式来写，或者参考官方文档 github.com/zircote/swa…

数据同步方式

目前可选增量更新、全量更新、仅添加新的 API 三种形式，API 研发管理平台 推荐采用增量更新的方式。每次同步之后，系统都会自动生成 API 历史版本方便回滚文档，因此即使操作失误也不用担心。

生成API文档的默认状态

扫描得到的新增加的API的默认状态，默认是启用状态

码云

配置项

说明

代码仓库类型

选择码云

代码仓库地址

项目仓库的访问url，如gitee.com

空间名

您在码云创建的空间名称，如eolinker

仓库名

空间中的仓库名称，如goku

访问私钥

码云的私人令牌

需要扫描的分支

默认为 master 分支，您也可以选择实际需要扫描的代码分支

需要扫描的 API 目录路径

API 层相关代码的存放路径

需要扫描的数据结构目录路径

数据结构相关配置信息的存放路径

目标语言

Java 或 PHP

注解格式

默认为 Swagger 2.0，代码注释编写的格式参考下面的形式来写，或者参考官方文档 github.com/zircote/swa…

数据同步方式

目前可选增量更新、全量更新、仅添加新的 API 三种形式，API 研发管理平台 推荐采用增量更新的方式。每次同步之后，系统都会自动生成 API 历史版本方便回滚文档，因此即使操作失误也不用担心。

生成API文档的默认状态

扫描得到的新增加的API的默认状态，默认是启用状态

同步配置

完成数据源配置后，需要对同步的业务逻辑进行配置。

数据同步方式

支持三种同步方式：增量更新、全量更新、仅添加新的API

  • 增量更新

  • 更新数据时，判断 API 和 API 的内容是否有变化，仅同步发生变化的部分。如增加新的 API、修改发生变化的 API 内容。适用于绝大多数情况，当您不知道如何选择时请选择这种方式，避免丢失数据。

  • 因为要做增量对比，故在选择增量更新时，需要选择用于判断API的唯一标识。可选择接口标识（operationId）、接口地址与请求方式结合判断、接口名称，三种方式。

  • 全量更新

  • 更新数据时，清空现有项目内所有 API，重新从数据源导入 API 信息。注意这种方式会导致之前编辑的 API 内容丢失，仅适用于小部分情况下重新导入所有 API 信息。

  • 仅添加新的****API

  • 更新数据时，判断是否有新增的 API，如果有新增的API则添加新的 API，但不会删除已经不存在的 API，也不会更新现有 API 文档的内容。

状态设置 & 新文档分组

无论选择哪种数据同步方式，均可以分别配置新生成的文档状态和发生变更的文档状态。状态可选项为所有API文档的状态。

我们也可以设置新生成的文档添加到哪个分组下，默认是根目录。

avatar
文章
阅读
粉丝