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 文档

 

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

到了这里,关于Apikit 自学日记:自动生成 API 文档的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • Apikit 自学日记: Apikit 如何发起测试

    进入 API 文档详情页,点击上方 测试 标签,进入 API 测试页,系统会根据API文档自动生成测试界面并且填充测试数据。   首先填写好请求参数。   您可以输入或导入请求头部。批量导入的数据格式为 key : value ,一行一条header信息,如: 请求体提供了五种类型: Form-data(表

    2024年02月09日
    浏览(44)
  • Apikit 自学日记:测试模板

    在 APIKIT 中,你可以将重复的测试步骤添加到测试模板库中,并且在测试用例中引用测试模板来实现复用测试步骤的目的。如将用户登录、清理数据库等操作作为测试模板,并将该用例引入到多个测试用例中,减少不必要的工作。 在自动化测试界面,选择用例模板,点击 添加

    2024年02月16日
    浏览(42)
  • Apikit 自学日记:添加测试步骤-脚本步骤

    在流程测试用例界面,进入用例管理,点击 添加脚本[ Javascript ] 按钮:   进入编辑用例页面,点击 新 API 测试 新建一个 API 请求。   API 自动化测试平台为代码模式的测试用例设计了一套简单的API信息模板,因此只需要极少的代码即可完整地描述API信息,模板中各个字段含义

    2024年02月12日
    浏览(42)
  • tp6的runtime/Logs目录下产生大量日记文件,怎么取消自动生成?

    一开始查了好多网上提供的,很幸运都是抄袭别人的,没一个成功,最后无奈只能自己解决方法 其实很简单,不用修改config/log.php文件,没用因为只要有登入错误,警告,消息或者sql错误都会写入 解决方法: 关闭调试模式 配置数据库文件  .env文件 true改为false即可  总结:

    2024年02月16日
    浏览(80)
  • Apifox自动生成接口文档

    官方文档:Apifox - API 文档、调试、Mock、测试一体化协作平台 - 接口文档工具,接口自动化测试工具,接口Mock工具,API文档工具,API Mock工具,API自动化测试工具         打开 IDEA Preferences(Settings) Plugins ,搜索 Apifox Helper 官方地址:Apifox IDEA 插件快速上手 | Apifox 帮助文档

    2024年02月12日
    浏览(43)
  • postman自动生成接口文档

     点击:  会自动生成一个文件夹    点击图表,修改名字 新建一个请求,到时候会自动保存到文件夹里面,但是保存前看清楚保存的名字    点击三个点-》点击export即可

    2024年02月11日
    浏览(47)
  • 自动生成数据库设计文档,支持多数据源批量生成(Word文档)

          在做项目时通常使用PowerDesigner设计数据库,但在项目完成交付项目给客户的时候常常需要一份Word版本的数据库文档给客户,你不能指望每个客户都会用PowerDesigner,所以基于当前开发数据库生成数据库文档就是最佳选择,如果手动编写数据库文档那将是一件非常痛苦的

    2024年04月23日
    浏览(46)
  • Mongodb 集合插入文档自动生成ObjectId

    Mongodb 使用以下几种方法来插入文档 , Mongodb V5.0+ 使用 mongosh 客户端: 插入单个文档 db.collection.insertOne() 将单个 文档插入到集合中。 如果该集合当前不存在,则插入操作将创建该集合。 如果文档未指定_id字段,则将在插入之前 mongod 添加该字段并为文档_id分配唯一的字段

    2024年02月12日
    浏览(46)
  • word文档批量生成工具(附免费软件)(按Excel表格内容自动替换内容生成文档)

    批量生成word文档是让人无比厌恶但有时又不得不做的事情。比如学校要给拟录取的学生发通知书,就可能需要批量生成一批只有“姓名”、“学院”和“专业”不同,其他内容都相同的word文档以供打印(事实上直接生成pdf是更好的选择,这个以后有心情可以弄一下)。 要实

    2024年02月11日
    浏览(48)
  • 7. 实现 API 自动生成

    目录 1. pom.xml中引用依赖 2. 引入相关的依赖 3. 编写配置类 4. application.yml 中添加配置 5. API 常用注解  6. 访问 API 列表 7. API 导入 Postman 使用 Springfox Swagger生成 API,并导入 Postman,完成API单元测试。 Swagger 简介 :Swagger 是⼀套 API 定义的规范 ,按照这套规范的要求去定义接口

    2024年02月12日
    浏览(35)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包