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

功能入口：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

GitLab

码云

同步配置

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

数据同步方式

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

• 增量更新
• 更新数据时，判断 API 和 API 的内容是否有变化，仅同步发生变化的部分。如增加新的 API、修改发生变化的 API 内容。适用于绝大多数情况，当您不知道如何选择时请选择这种方式，避免丢失数据。
• 因为要做增量对比，故在选择增量更新时，需要选择用于判断API的唯一标识。可选择接口标识（operationId）、接口地址与请求方式结合判断、接口名称，三种方式。
• 全量更新
• 更新数据时，清空现有项目内所有 API，重新从数据源导入 API 信息。注意这种方式会导致之前编辑的 API 内容丢失，仅适用于小部分情况下重新导入所有 API 信息。
• 仅添加新的API
• 更新数据时，判断是否有新增的 API，如果有新增的API则添加新的 API，但不会删除已经不存在的 API，也不会更新现有 API 文档的内容。

状态设置 & 新文档分组

无论选择哪种数据同步方式，均可以分别配置新生成的文档状态和发生变更的文档状态。状态可选项为所有API文档的状态。
我们也可以设置新生成的文档添加到哪个分组下，默认是根目录。