吐槽接口文档——什么是优秀的接口文档

Posted 2021-09-03 隔壁王书

昨天说了合格的接口文档，今天继续唠一唠，什么是我觉得优秀的接口文档。

项目部分

首先，优秀的接口文档在合格的接口文档上最显著的一个特征，就是在描述几种项目必须要素基础上，要给出更加详细的说明以及所涉及到的技术细节，甚至要给出关键代码逻辑的demo。例如，除了文字版叙述加密、解密和验证算法以外，要给出测试语言所能够时直接抄用的代码demo。
其次，在项目所涉及到的请求方法这个要素上，要给出更加详细的方法使用规范；在传参格式这个要素上，要给出传参的具体请求和响应内容的Demo。虽然项目中总有一些特殊的接口会违反这些规范，有的时候也是不可避免的，特别是在跟其他系统对接的时候，很难做到全部统一。但是还是需要开发。在编写文档的时候，给出一个统一的格式，这样能够极大的减少测试人员的工时消耗。
一个优秀的接口文档。最直观的就是它的目录部分。这部分包含着整个项目结构文档的功能模块集合，因此要让人看了接口文档，对整个项目的业务功能有一目了然之感。而且接口文档模块要有足够的文字说明，模块的划分要与模块下面的接口有很强的关联性，特别是在url的划分上。我认为优秀的接口文档的一个重要体现就是测试人员拿到一个接口的地址，然后能在这个接口文档的成绩目录中找到这个接口准确的位置，而不用通过全局搜索。

接口部分

对于优秀的接口文档来说，接口部分除了以上的几个要素以外，还需要对接口请求参数的参数名进行文字说明，因为有时候如果参数特别复杂的话，会不太能够看清楚参数名、得到参数业务的相关情况。这里我觉得好的方法有最两种，一种是在定义参数名称的时候有一定的统一规范，且全局对于同一业务使用统一的英文单词，对于相同业务的行为进行统一的命名规范。例如添加用户这个接口可以用adduser，而不是使用at customer或者insertuser这样的词汇，以免造成同一业务逻辑在不同的接口有不同的名字。
优秀的接口文档，另外一个直观的体现就是让测试人员在简单阅读接口文档之后，能够迅速的调通这个接口，这依赖于接口文档中给出的请求参数的demo。这个对测试人员来说非常重要，因为如果一个接口请求不通的话，原因可能是多个因素叠加在一起的。测试人员很难在接手一个新接口的时候，就把这些因素区分开，所以就需要一个正确的请求参数组合来帮助测试人员迅速的调试通过接口。
除了以上几个方面以外，我觉得还有一个对我来说非常重要的接口测试文档内容就是参数来源。因为在我实际做测试的过程当中，大多数的接口参数都是从另外的接口响应中获取的。一般规定的接口的范围可能是1~1万这样子，但是对于我要测的业务来讲，只可能就是几个。正常，我们会对接口先进行接口参数验证的验证，也就是冒烟测试。但是越过这个阶段之后，我们需要进行更多的是业务相关的一个接口，测试文档参数以及响应数据来源，一般都是需要跟其他业务相关的接口有关联性的。接口测试不像ui测试，可以通过页面去查看相关的内容，接口测试面对的就是一堆json数据。如果接口的参数命名不够统一，不够规范的话，接口测试人员很难去找到业务测试中接口数据的验证值。所以我认为接口测试参数来源非常重要。

维护

对于优秀的接口文档而言，接口文档的实时性和准确性已经得到了保证，需要提高的就是文档变更的次数减少以及变更时的人员通知。如果是新接口的话。第一次提测过程当中，接口文档的变更是非常难以避免的，这里测试人员要有心理准备。但是对于旧接口，维护和更新是低频率发生的事情，但是一旦发生处理不及时，就会导致一些故障。
最好的接口文档就是一次编写，永不维护的。当然这是不太可能的。优秀的接口文档，不止在于文档本身，还在于开发、测试相互的沟通效率。
最后，工欲善其事，必先利其器，这里推荐一个接口文档工具：Eolinker，给我省下了很多功夫。
使用地址：www.eolinker.com