功能入口: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: 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 |
代码仓库地址 | 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 文档的内容。
状态设置 & 新文档分组
无论选择哪种数据同步方式,均可以分别配置新生成的文档状态和发生变更的文档状态。状态可选项为所有API文档的状态。文章来源:https://www.toymoban.com/news/detail-512061.html
我们也可以设置新生成的文档添加到哪个分组下,默认是根目录。文章来源地址https://www.toymoban.com/news/detail-512061.html
到了这里,关于Apikit 自学日记:自动生成 API 文档的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!