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

这篇具有很好参考价值的文章主要介绍了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类型的数据，否则会提示无法访问该地址。

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

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

配置项	说明
代码仓库类型	选择Github
代码仓库地址	默认填写 GitHub: Let’s build from here · GitHub
用户名	Github 账户名称
仓库名	Github Repository 仓库名称
访问私钥	仓库私人令牌在GitHub Repository 的Settings->Developer settings->Personal access tokens中生成
需要扫描的分支	默认为 master 分支，您也可以选择实际需要扫描的代码分支
需要扫描的 API 目录路径	API 层相关代码的存放路径
需要扫描的数据结构目录路径	数据结构相关配置信息的存放路径
目标语言	Java 或 PHP
注解格式	默认为 Swagger 2.0，代码注释编写的格式参考下面的形式来写，或者参考官方文档 swagger-php/Examples at 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub
数据同步方式	目前可选增量更新、全量更新、仅添加新的 API 三种形式，API 研发管理平台推荐采用增量更新的方式。每次同步之后，系统都会自动生成 API 历史版本方便回滚文档，因此即使操作失误也不用担心。
生成API文档的默认状态	扫描得到的新增加的API的默认状态，默认是启用状态

配置项	说明
代码仓库类型	选择Gitlab
代码仓库地址	GitLab 有线上版本和用户自己搭建私有云版本，线上版本可以填写 The DevSecOps Platform \| GitLab，如果是自己部署的 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，代码注释编写的格式参考下面的形式来写，或者参考官方文档 swagger-php/Examples at 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub
数据同步方式	目前可选增量更新、全量更新、仅添加新的 API 三种形式，API 研发管理平台推荐采用增量更新的方式。每次同步之后，系统都会自动生成 API 历史版本方便回滚文档，因此即使操作失误也不用担心。
生成API文档的默认状态	扫描得到的新增加的API的默认状态，默认是启用状态

配置项	说明
代码仓库类型	选择码云
代码仓库地址	项目仓库的访问url，如Gitee - 企业级 DevOps 研发效能平台
空间名	您在码云创建的空间名称，如eolinker
仓库名	空间中的仓库名称，如goku
访问私钥	码云的私人令牌
需要扫描的分支	默认为 master 分支，您也可以选择实际需要扫描的代码分支
需要扫描的 API 目录路径	API 层相关代码的存放路径
需要扫描的数据结构目录路径	数据结构相关配置信息的存放路径
目标语言	Java 或 PHP
注解格式	默认为 Swagger 2.0，代码注释编写的格式参考下面的形式来写，或者参考官方文档 swagger-php/Examples at 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub
数据同步方式	目前可选增量更新、全量更新、仅添加新的 API 三种形式，API 研发管理平台推荐采用增量更新的方式。每次同步之后，系统都会自动生成 API 历史版本方便回滚文档，因此即使操作失误也不用担心。
生成API文档的默认状态	扫描得到的新增加的API的默认状态，默认是启用状态

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

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

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