接口文档（概述）

               

  作为接口自动化测试教程的最后一章，我们来讲述一下影响接口自动化测试工作的一个重要因素：接口文档。测试人员对脚本语言的熟练程度，检测点的设置技巧等相关的技能确实影响着接口自动化的实施，可以说接口自动化测试之本接口文档却是重中之重。

7.1 接口文档的特点

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

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

7.2 接口文档的结构

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

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

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

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

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

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

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

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

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

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

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

（6）功能说明。说明接口名称的具体功能说明。

（7）其它说明。

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

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

7.3 接口文档缺失

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

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

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

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

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

7.4 本章小结

   本章是接口自动化测试教程的最后一章，我们在本章讲述了影响接口自动化测试的最根本的接口文档的相关知识。虽然我们不能要求开发完全按我们的要求写接口文档，可是我们可以给领导建议应该写成什么样子的，这样有利于我们的工作。通过本教程的学习，相信大家能动手编写自己的接口自动化测试用例，并投入到正式的工作中。

  “临渊羡鱼，不如退而结网”，一定要动手去做，在不断的实践中才能积累丰富的经验。不然就算看再多的教程也只是停留在理论上，遇到了实际问题时还是无从下手。最后，祝大家学习愉快！！