接口测试之接口api文档的重要性

接口文档的特点

接口文档，顾名思义就是对接口说明的文档。好的接口文档包含了对接口URL，参数以及输出内容的说明，我们参照接口文档就能编写出一个个的测试用例。而且接口文档详细的话，测试用例编写简单，不会遗漏。

如果一个接口文档没有写清楚，你从文档中分不出哪些儿参数是必需的，哪些儿是非必须的，而且没有参数的取值说明，返回值的结构等信息的话，测试人员是无法编写相应的测试用例的。但是由于开发人员不愿意写文档，所以很多接口文档相对来说比较简单，模糊不清，这对我们做接口自动化测试是很大的阻碍。

7.2 接口文档的结构

接口文档可以包含很多信息，有的愿意写就可以多写的，不太愿意写的话，就写的信息相对来说会少点儿。不过，下面几项内容必须有，这是我们使用接口中和测试接口的依据：

（1）接口名称。标识各个接口的简单说明，如登录接口，获取项目详情接口等。

（2）接口URL。接口的调用地址，在测试环境下前面的域名可能不一样，不过接口名是不会变的。

（3）调用方式。接口的调用方式：Post/Get方式，决定了如何调用接口及传递参数。

（4）    参数。接口需要传递的参数，参数需要增加些儿说明：

（a） 参数值类型说明：参数值要说明一下，只支持字母，数据，特殊字符或是字母数据混搭。

（b）参数长度说明：参数接收最大多少个的字符串，或是最大是多少的数值等。

（c） 参数取值范围：像枚举型的参数，只接收什么范围内的数据，如1-5等。

（d）参数的配合说明：有些儿参数需要配合起作用的，如：offset和count参数。

（e） 参数是必需的还是非必需的。

（5）返回值。接口的返回值说明需要包含正确和错误的情况，正确的情况下有哪儿数据，错误的情况下会有什么提示？

（6）其他的一些儿说明。上面的说明是通用的，还有其他的一些儿说明，如必须是登录状态调用，或是版本号等说明，在某些儿情况下也需要说明一下。

严格要求的公司会要求接口开发人员标明上面相关的接口说明，此时我们做接口测试的时候，就可以参照文档来转化我们的测试用例。但目前国内很多公司不太注重文档，接口信息不全是常有的事情。

7.3 接口文档缺失

针对目前接口文档信息不全或是没有接口文档的情况下，如果上面的领导要求我们做接口自动化测试，这无异是一个非常艰辛的任务。但是奉承着“兵来将当，水来土掩”的原则，我们要想着解决办法。

（1）完全没有接口文档。这个情况是最麻烦的，我们要找开发人员来商量 ，最好能补个接口文档，如果实在来不及那就给个调用接口的实例。实例中会有接口地址，参数等信息，我们去测试环境中调用一下，就能看到返回结果的情况。

（2）接口文档信息不全。信息不全这个最常见，像参数说明缺少啊，没有说明哪些儿是必需的参数，哪些儿是非必需的，或是没有说明取值范围等。此时我们能问开发就问开发，如果不太方便，就要做尝试：一般非必需的参数不会做容错的判断，必需的参数检测的方面比较全面。

（3）文档不是最新的。接口的后续的工作中被修改或是优化过，我们按接口文档上的说明去调用，返回和预期的不一样。通知开发更新文档，然后用最新的文档再去修改测试用例。

这个接口文档需要和接口开发人员做好约定，开发新接口时要把接口信息写清楚，如果更新原来的接口，要及时更新接口文档。同时在写接口自动化测试用例的时候，要多和开发人员沟通，只有通过大家的一起努力，才能把工作做的越来越好。