本文关于如何高效管理接口文档？适合写API接口文档的管理工具有哪些？

01 痛点

如果你负责测试的项目是一个前后端分离的项目，回忆下是不是有如下场景：

某个项目是前后端各自进行开发，开发完成后接口文档发布在了 swagger 上。你负责这个项目的服务端测试。

首先进行接口测试：熟练的打开 postman 导入 swagger 文档,然后开始进行接口测试。

接口测试完成后,准备开始性能测试。又要将 swagger 接口文档将新接口迁移到 jmeter 上，然后开始编写压测脚本。

你进行接口回归测试,发现接口测试脚本失败,此时给开发提了一个 bug（实际是因为后端修复 bug 改了接口参数）。

开发跑过来给你说,接口文档有变动忘了个你说了,此时你只能默默的修改接口测试用例。

服务上线一段时间后。某天,新员工开发小黄想想看下这个项目之前的接口文档,发现测试环境接口 swagger 地址打不开了,没有地方可以看接口文档。

︾

其实上边这些问题,在日常工作中很常见。其根本原因是接口文档缺乏统一管理,有的团队喜欢把接口文档写在内部协作文档平台里、有的团队喜欢写在 git 代码仓库里,它们的存放目录及目录深度各有不同。当后来人想要看接口的历史文档时,简直无从查起,许多文档就这样遗失了。

你有没有想过拥有一个,可以同时解决数据同步、调试、Mock、自动化测试的接口文档管理工具？

02 什么是eolink

结合 API 设计、文档管理、自动化测试、监控、研发管理和团队协作的一站式 API 生产平台，从个人开发者到跨国企业用户，Eolink 帮助全球超过 30 万开发者和数万家企业更快、更好且更安全地开发和使用 API。

03 为什么选eolink

支持 HTTP(S)、Websocket、TCP、UDP 等主流协议，通过代码注解自动生成 API 文档,或者从 API 文档反向生成所有常见开发语言和框架的代码，节省 API 设计和开发时间。强大的 API 版本和变更管理让你不放过 API 的任何变动。

支持所有主流协议

代码自动生成 API 文档

API 文档自动生成代码

API 版本管理

API 变更通知

超方便的 API 测试

支持多种方式快速发起 API 测试，自动生成随机测试数据和测试用例，一键对 API 进行批量回归和冒烟测试，并且立刻得到丰富详细的测试报告，让繁琐的 API 测试变得如此简单。

支持在线、本地、客户端进行测试

一键进行回归/冒烟测试

快速创建测试用例

自动生成测试数据

丰富详细的测试报告

0 代码的 API 自动化测试

不需要编写代码,通过拖拉拽即可创建 API 测试流程，API 文档和测试步骤自动关联，当 API 文档发生变化时自动同步到测试用例，极低的学习和维护成本。并且通过定时自动测试将测试报告推送到邮箱、钉钉、企业微信、飞书、Jenkins 等平台，与 CI/CD 流程无缝结合。

与 API 文档关联与自动同步

0 代码，拖拉拽完成测试流程编排

统一管理测试数据

对数据库进行操作

定时自动测试

测试报告自动推送

04 eolink初体验

我们看一下 eolink 是如何使用接口文档管理工具、接口文档生成工具这两个功能。解决日常工作中,涉及接口文档变更问题。

一、安装注册

eolink 是跨平台的工具,支持 macOS(Intel+M1)、Linux、windows(32 位、64 位),在官网 https://www.eolink.com, 选择对应系统的安装包下载安装即可用。

首次使用注册账号就可以使用。登录 eolink 后,可以看到左侧的项目、环境、高级功能。点击项目,可以看到 API 文档管理。

接口文档管理

eolink 支持多种导入数据方式,比如 swagger、jmeter、yapi、rap 等常用接口测试工具,这里我们沿用使用 swagger 工具导入数据,其他工具导入的方式也大同小异,后续再介绍。

导入接口数据后的接口列表展示效果,可以看到接口名称、接口路径、协议等参数。

随便点击一个接口,可以看到基本信息、请求参数、响应内容。

点击修改文档/新建接口,可以编辑接口的信息。点击保存,可以触发消息通知给相关人员。

自动同步接口

在研发过程中,开发人员修改代码,重启服务后 swagger 工具会自动更新,但是 eolink 中还是旧的接口数据,这就会导致接口文档不及时更新的问题。

在 eolink 可以通过代码注解或者其他工具自动生成或抓取 API 文档,是怎么做到的呢?

输入项目的 swagger 地址,数据同步方式选择增量更新,这样做的好处是在旧接口文档的基础上增量修改,避免了重复新增接口数据。

在线接口文档

根据定义好的接口,生成可以通过浏览器访问的 web 地址分享给其他人。

在线接口文档适合提供给本地没有安装 eolink 客户端的用户,方便大家随时可以查看接口信息、进行接口测试。

另外在设置分享页面,设置可见项目环境、设置分享的功能模块，例如 Mock、API 测试、API 测试用例等等。

在线访问地址

https://www.eolink.com/share/index?shareCode=i98qn5

接口调试

当我们设计好接口测试用例之后，可以调试看看效果。

以查询商品接口为例，进入执行页面，填写完成参数值，选择运行环境，点击运行即可发起一个简单的请求，页面下方可查看接口响应、请求详情。

接口调试参数可以保存为一个接口测试用例用例，方便下次调试或者团队成员测试使用。

执行接口参数用例的目的是验证不同测试场景下接口的正确性，例如密码错误、用户名非法、参数值空等等。

如果需要从响应提取信息以供后续请求使用，通过可视化 UI 操作即可 0 编码实现提取变量和对返回值断言的操作。

入口在后置操作里面，我们从响应提取一 code 存为环境变量，并断言响应里的 code 字段值为"200"。

可以查看内置函数手册,使用内置函数进行断言,如果接口返回格式是 json 格式,可以使用 jsonpath 获取需要的字段值,进行断言。

内置函数手册地址：

https://help.eolink.com/#/tutorial/?groupID=c-709&productID=13

后置脚本例子,获取 code 字段参数:

var info = eo.http.response.get("info")

var code = eo.jsonpath("code",info);

eo.info(code);

if(code !=200){

   eo.error("接口断言失败"); 

}

1

2

3

4

5

6

7

丰富的内置函数,基本上满足日常测试工作要求,包括: 单接口测试、串联接口测试。

05 总结

随着项目不断的迭代,项目也越来越复杂。带来的问题是,接口入参和出参会不断地新增、修改。

测试人员面临的挑战是:

1、如何获取最新的接口文档

2、如何降低接口测试的成本

3、如何提高团队协作的效率

eolink 既能管理接口又能做自动化测试、好用好看还免费的接口文档工具, 还不赶紧用起来~

适合写API接口文档的管理工具有哪些

现在越来越流行前后端分离开发，使用ajax交互。所以api接口文档就变的十分有意义了，目前市场有哪些比较优秀的接口文档管理工具呢？

1.Showdoc：

一个非常适合IT团队的在线API文档、技术文档工具。

2.eoLinker

　　eoLinker拥有业内最强的接口管理功能，无论你是创业团队还是成熟企业，eoLinker将满足你的所有接口管理需求。在eoLinker上编写或者导入接口文档，邀请团队成员加入项目，接着进行在线的接口测试，并且提供Mock接口给前端进行对接，后续通过完善的文档版本管理以及团队协作功能，不断地对项目进行迭代，提高项目整体的开发效率！

主要功能

　　·快速全面地管理接口文档 :1.UI可视化文档，2. 支持表单、RESTful、Raw等设计规范，3. 通过注释生成文档，4. 版本管理，5. 支持富文本/Markdown，6. 分组管理，7. 星标标注。

　　·测试接口是否正常运作：1. 支持在线、本地（localhost）测试，2. 支持跨域测试，3. 支持文件测试，4. 强大的参数构造器。

　　·Mock API实现敏捷开发：1. 根据文档自动生成校验数据，2. 支持请求协议、请求方式校验，3. 支持简易Mock、高级Mock（MockJS），4. 支持跨域调用。

　　·了解团队成员动向: **1. 团队人员管理，,2. 支持设置人员读写权限，3. 支持成员昵称，4. 支持通过链接邀请成员。

　　·专业版：1. 强大的插件支持，2. 代码生成，3. 测试用例，4. 空间日志，5. 高级权限管理，6. 5天 * 10小时 专业客户成功部门一对一支持。

3.MinDoc

　　MinDoc 是一款针对IT团队开发的简单好用的文档管理系统。MinDoc 的前身是 SmartWiki 文档系统。SmartWiki 是基于 PHP 框架 laravel 开发的一款文档管理系统。因 PHP 的部署对普通用户来说太复杂，所以改用 Golang 开发。可以方便用户部署和实用，同时增加Markdown和HTML两种编辑器。其功能和界面源于 kancloud 。

[](javascript:;)主要功能

　　·项目管理，可以对项目进行编辑更改，成员添加等。

　　·文档管理，添加和删除文档，文档历史恢复等。

　　·用户管理，添加和禁用用户，个人资料更改等。

　　·用户权限管理 ， 实现用户角色的变更。

　　·项目加密，可以设置项目公开状态，私有项目需要通过Token访问。

　　·站点配置，二次开发时可以添加自定义配置项。

　　·附件管理，可管理所有项目中上传的文件。

　　·项目导出，目前支持导出 PDF 格式项目。

　　·系统日志。

　4.apizza

　　极客专属的api协作管理工具 免费的团队协作，在线模拟调试，快速生成api文档，导出离线版文档

主要功能

　　·api跨域调试量身定制的chrome插件，本地，在线接口，都可以调。

　　·免费的团队协作 免费的团队协作工具，极致的文档编写体验，加快开发效率。

　　·安全的云端存储 安全可靠的云端存储服务，企业安全版支持本地数据中心。

　　·一键分享 与团队共享你的API文档。

　　·支持Postman，Swagger格式 导入Postman/Swagger Json 生成文档。

　　·导出离线文档 导出离线文档，部署本地服务器。

　　·api Mock 根据文档自动生成返回结果，提供独立URL方便前端测试

　　·支持多种文档 http接口文档，markdown说明文档

　　[图片上传中...(image.png-150c34-1539666393114-0)]

　5.RAML

　　用 YAML 文件格式编写，强大的官方支持，官方提供 atom 插件，支持语法智能提示及校验，编写快速简单。

　　主要功能

　　·支持 examples

　　·支持 schema 校验

　　·支持工具测试

　　6.其他工具

　　1).Swagger:

　　通过固定格式的注释生成文档. 省时省力,不过有点学习成本。

　　2).apidoc:

　　可以根据代码注释生成web api文档，web接口的注释维护起来更加方便，不需要额外再维护一份文档。

　　3).RAP：

　　一个可视化接口管理工具 通过分析接口结构，动态生成模拟数据，校验真实接口正确性， 围绕接口定义，通过一系列自动化工具提升我们的协作效率。

　　4.APIJSON：

　　客户端可以定义任何JSON结构去向服务端发起请求,服务端就会返回对应结构的JSON字符串,所求即所得。

上述就是小编为大家整理的如何高效管理接口文档？适合写API接口文档的管理工具有哪些相关内容。

国内(北京、上海、广州、深圳、成都、重庆、杭州、西安、武汉、苏州、郑州、南京、天津、长沙、东莞、宁波、佛山、合肥、青岛)eolink软件分析、比较及推荐。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。