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

Posted 2021-09-01 隔壁王书

最近对接了几个测试管理平台的接口文档，总地来说，感触良多。
首先我个人工作经验最大的一个感触就是。如果说一件事情做好，能够最大的提升工作效率，我觉得就是文档规范。对于接口测试来说，接口文档。就是最要命的卡脖子技术。
那么今天我分享一下我自己对一个合格和优秀的接口文档的认识。这里我认为的合格的接口文档就是本分，优秀的接口文档就是卓越。

合格的接口文档

项目部分

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

对于一个项目来说，接口肯定会比较多，甚至上百上千都有可能，这就要求接口文档必须进行模块化划分。是为了阅读和编写的时候的方便点，也是为了能够更好的管理接口文档。
不同模块划分要有一定的标准，而且这个标准要和接口的url统一。注意，这个必须是强标准，不能存在差不多、可能、就这样这种词汇。
同时，模块的划分要与模块下面的接口有很强的关联性，特别是在url的划分上。因为在测试的过程中，我们基本不会再去翻回头看接口文档。如果能通过url判断这个接口所在的模块以及这个接口的功能，那对于测试来说是一件极其幸福的事情。

接口部分

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

对于请求非参数的数据通常包含以下几个方面。
一是请求的地址。二是请求的方法。三是接口的业务。
PS：最好写上开发名字。

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

对于接口响应。一般包含以下几项要素，第一就是响应的demo。想用中异常情况的处理。这个异常情况包含了http响应异常以及业务响应异常，特别是业务响应异常中必须要包含业务响应的code以及业务响应code所对应的业务场景。

维护

对于测试人来而言，接口文档未能及时的更新，是导致测试用例执行失败经常出现的原因。所以在进行接口测试之前，一定要确保接口文档的准确性。在一些场景下，接口文档是需要人手动去维护的，而手动维护就带来两个问题。
第一个问题是手动维护所带来的错误，第二个问题是手动维护所带来的延迟。
要解决这两个问题，方法是多种多样的，既有从技术方面的，也有从管理方面的，还有从跨部门协调方面的，这个大家可以在网上搜一搜。合格的接口文档。需要在提测之前保证接口文档的准确性实时性。以及在这提测的过程中，及时的修改和维护相关文档。以及通知到相关测试人。

如果发生接口文档必须有所更改的场景。那么就非常的考验这个接口的设计者。
最后，工欲善其事，必先利其器，这里推荐一个接口文档工具：Eolinker，给我省下了很多功夫。
使用地址：www.eolinker.com

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