吐槽接口文档(一)——什么是合格的接口文档

eoLinker 技术开发  2021-09-01 17:50:32

最近对接了几个测试管理平台的接口文档,总地来说,感触良多。

首先我个人工作经验最大的一个感触就是。如果说一件事情做好,能够最大的提升工作效率,我觉得就是文档规范。对于接口测试来说,接口文档。就是最要命的卡脖子技术。

那么今天我分享一下我自己对一个合格和优秀的接口文档的认识。这里我认为的合格的接口文档就是本分,优秀的接口文档就是卓越。

 

合格的接口文档

项目部分

合格的接口文档必须包含以下几种要素。

首先是要对项目进行介绍。除去业务支持的简单介绍以外,还必须对项目的环境和host它的对应关系、项目所涉及到的请求方式、各个请求方式的传参格式、以及项目规定的请求头内容(包括不限于项目中所遇到的加密解密算法以及多语言实现Demo),都要给出详细的说明。

 

对于一个项目来说,接口肯定会比较多,甚至上百上千都有可能,这就要求接口文档必须进行模块化划分。是为了阅读和编写的时候的方便点,也是为了能够更好的管理接口文档。

不同模块划分要有一定的标准,而且这个标准要和接口的url统一。注意,这个必须是强标准,不能存在差不多、可能、就这样这种词汇。

同时,模块的划分要与模块下面的接口有很强的关联性,特别是在url的划分上。因为在测试的过程中,我们基本不会再去翻回头看接口文档。如果能通过url判断这个接口所在的模块以及这个接口的功能,那对于测试来说是一件极其幸福的事情。

 

接口部分

在接口部分,接口文档的格式会比较统一。一般也都会包含以下几种要素。第一种是请求(非参数),第二种是请求参数,第三种就是请求的响应结果。

 

对于请求非参数的数据通常包含以下几个方面。

一是请求的地址。二是请求的方法。三是接口的业务。

PS:最好写上开发名字。

 

对于请求的参数。一般包含几下几项。要素第一就是参数的整体格式,具体的参数名、参数值、关于参数值的话,一定要说清楚参数的范围、校验的规则。

 

对于接口响应。一是响应的demo,二是响应中异常情况的处理。这个异常情况包含了http响应异常以及业务响应异常,特别是业务响应异常中必须要包含业务响应的code以及业务响应code所对应的业务场景。

 

维护

对于测试人来而言,接口文档未能及时的更新,是导致测试用例执行失败经常出现的原因。所以在进行接口测试之前,一定要确保接口文档的准确性。在一些场景下,接口文档是需要人手动去维护的,而手动维护就带来两个问题。

第一个问题是手动维护所带来的错误,第二个问题是手动维护所带来的延迟。

要解决这两个问题,方法是多种多样的,既有从技术方面的,也有从管理方面的,还有从跨部门协调方面的,这个大家可以在网上搜一搜。合格的接口文档。需要在提测之前保证接口文档的准确性实时性。以及在这提测的过程中,及时的修改和维护相关文档。以及通知到相关测试人。

 

如果发生接口文档必须有所更改的场景。那么就非常的考验这个接口的设计者。

最后,工欲善其事,必先利其器,这里推荐我们的接口文档工具:Eolinker,可以为接口相关工作省下很多功夫。

使用地址:www.eolinker.com

 

由于篇幅问题,吐槽分成两篇来发,感兴趣可以看看下一篇,什么是优秀的接口文档。

 

...全文
7678 14 收藏 10
写回复
10 条回复
切换为时间正序
请发表友善的回复…
发表回复

那么问题来了,接口文档谁来维护

回复

当然,一个好的接口文档能够给开发测试过程中带来很多便利;
但是,在实际工作中,你永远无法想到其他人是多么的愚蠢;
我2020年5月的时候,生产上出现问题,其他系统就调用我这个系统的接口,结果发现调不通,然后紧急修复,发现原来是对方系统的开发人员没有按照接口文档来开发,当时问他为什么不按照接口文档开发,
结果他说,“有接口文档,就一定要按照文档开发吗?”
直接把我怼的没话说。。。

回复 2

规范的接口文档很重要

回复

我一个实习生被测试接口,嗯,我学Java开发的,没有接口文档,只用一个手持机设备和一个平台让我测试,我太难了

回复 1
@拾玖年华就脱发 抓包
回复
@SillyBirder 抓包是什么,我才大三实习刚开始
回复
展开其他1条回复

再优秀的接口文档也比不上一段能运行通过的例子代码和测试数据。

回复 7
杨东杰 09-03

吐槽接口文档(二)——什么是优秀的接口文档 https://bbs.csdn.net/topics/600506365

回复
杨东杰 09-03

值得大力推荐的优质讨论

回复
发帖
API及云原生
创建于2021-06-07

113

社区成员

API接口以及云原生相关如容器、微服务等内容的讨论
帖子事件
编辑了帖子
2021-09-03 14:34
创建了帖子
2021-09-01 17:50
社区公告
暂无公告