吐槽接口文档（一）——什么是合格的接口文档

Eolink开发者社区

企业官方账号

2021-09-01 17:50:32

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

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

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

合格的接口文档

项目部分

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

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

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

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

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

接口部分

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

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

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

PS：最好写上开发名字。

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

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

维护

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

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

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

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

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

使用地址：www.eolinker.com

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

...全文

9058 14 打赏收藏转发到动态举报

写回复

用AI写文章

14 条回复

切换为时间正序

请发表友善的回复…

发表回复

对象被抛出 2021-09-24

打赏
举报

深有感触. 上学期应学校要求和几个同学开发了一个轻量级的微信小程序, 两周后上线. 前段时间告诉我们要写一份交接文档给下一届同学维护...从数据库模型, 到后台API和前端....写了上万字....

星星可比克 2021-09-23

打赏
举报

为什么不用Swagger

EloimEssaim丶 2021-09-10

打赏
举报

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

冰九的丸子汤 2021-09-06

打赏
举报

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