Apipost——让前端、后端、测试共用同一份API文档

时间:2023-01-06 19:55:18

作为软件开发从业者,API 调试是必不可少的一项技能,在这方面 Postman 做的非常出色。但是在整个软件开发过程中,API 调试只是其中的一部分,还有很多事情 Postman 无法完成,比如:API 文档定义、API 自动化测试等等,这些工作都是不同的角色、涉及不同的工具,沟通协作占据了大量的时间和精力。

现状:

后端常使用Swagger管理 API 文档、用Postman做调试,测试人员用JMeter做API自动化测试。开发过程中接口有变更需要与多端同步、联调时还会有各种问题,这就导致维护不同工具之间数据一致性非常困难、低效。

需求:

所以,能有一份联合各端的通用的API文档,就尤为重要。而Apipost,主要就是解决不协调的问题,让开发人员通过一套系统、一份数据,解决多个系统之间的数据同步问题。只要定义好接口文档,接口调试、数据 Mock、接口测试就可以直接使用,无需再次定义;接口文档和接口开发调试使用同一个工具,接口调试完成后即可保证和接口文档定义完全一致。高效、及时、准确!

对比:

针对API文档,我们可以对比一下Apipost与传统API文档、常用的Swagger之间的区别,更便于你选择适合自己的API管理工具:

1、传统API文档

很多团队的API文档依然在使用传统方式,即手动写一份类似于Word、excel的文档,将需要传递的数据填入,发给团队需要的成员,每次需要改动时都改好文件后再发送一次。对于后端人员来说,需要花大量的时间去专注于写文档;而Apipost,开发过程中调试完接口就能自动生成API文档,无需另外花时间去单独写。

2、Swagger文档

先来看看swagger与Apipost生成的API文档界面对比:

Apipost——让前端、后端、测试共用同一份API文档

【Swagger-API文档界面】

Apipost——让前端、后端、测试共用同一份API文档

【Apipost-API文档界面】

可以直观的看到,Apipost界面展示信息很全,左侧有菜单栏可以看到项目信息,中间是详细接口信息,包括项目/接口列表、基本接口信息(创建人、创建时间、更新时间,以及接口开发进度、状态、认证方式等)、参数、响应示例等;而且是纯中文界面,让人一看就很明白,想知道的信息都会展示在文档里。

而swagger的文档就展示了基本的API信息,接口列表也是平铺展示,想看单独的某个接口也没有菜单栏可以快速定位,只能手动一个一个去找;而且界面中很多都是英文,不太适合新人小白去上手和学习。

Apipost——让前端、后端、测试共用同一份API文档

【Swagger-API详细信息界面】


超越:

1、分享/导出文档

Apipost在分享API文档时还可以自定义分享,包括上传logo、设置密码查看、文档有效期、内外网分享等。

Apipost——让前端、后端、测试共用同一份API文档

【Apipost-API文档分享界面】

Swagger 要分享API文档首先需要导出文件,而导出却需要对应的插件和依赖包,比较繁琐复杂。而Apipost支持导出HTML、word和markdown格式的API文档,并且可还以一键去调试,快速定位接口问题,不需要多种工具来回切换。

Apipost——让前端、后端、测试共用同一份API文档

【Apipost-API文档快捷调试和导出界面】

2、归档管理

还有就是,Apipost生成的API文档虽然可以实时同步,但是开发人员并不是任何时候都想同步给别人。比如开发完的接口自己想改参数进行调试等,没必要或者不想同步给其他人员,怎么办呢?可以设置归档,接口被归档后,已经分享出去的文档就不会随着自己的改动而改变,自己修改接口信息时就不会同步给其他人了。

所以,无论小白还是职场老油条,Apipost都是值得去用的一款API管理工具。下至0基础小白上手就可以使用,上至行业专家可以高效协同管理团队并节省研发时间