读者问题：接口测试文档和报告

提问： 一份完整的接口文档应该是怎么样的？接口测试报告是怎么样的？有没有模板参考一下

答：接口文档，可以有很多种形式。

以最常见的HTTP协议下的接口为例，首先对整套接口的鉴权等机制要做个说明。

例子：https://developer.github.com/v3/

这里列出了他这套接口支持什么鉴权登录方式，参数传递方式，预定义的常见错误等等。

然后一般对每个具体的接口需要包括

1.简单描述

2.接口的URL

3.HTTP方法

4.参数

5.调用数据举例

举个例子：以下是 Github 的接口文档中对于“列出某个用户点了赞的项目”的接口文档

来自https://developer.github.com/v3/activity/starring/#star-a-repository

List repositories being starred --- 这是标题

List repositories being starred by a user. --- 这是对接口功能的简单描述：列出指定用户点过赞的项目

GET /users/:username/starred --- 这里指明了用Get方法和这个URL来调用这个接口。其中:username表示接口URL中可变的部分

List repositories being starred by the authenticated user.这是另一种调用方式，这里也是对接口功能的简单描述：列出当前登录的用户点过赞的项目

GET /user/starred -- 这里指明了用Get方法和这个URL来调用这个接口。

Parameters ---这里具体介绍了可选参数的参数名，数据类型，和业务意义描述

Response --- 这里给出了一个正确的调用后得到的返回值的例子

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

[
  {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
-----这个例子中间太长我删掉了-----
    "archived": false,
    "pushed_at": "2011-01-26T19:06:43Z",
    "created_at": "2011-01-26T19:01:12Z",
    "updated_at": "2011-01-26T19:14:43Z",
    "permissions": {
      "admin": false,
      "push": false,
      "pull": true
    },
    "allow_rebase_merge": true,
    "allow_squash_merge": true,
    "allow_merge_commit": true,
    "subscribers_count": 42,
    "network_count": 0
  }
]a

除了这种形式之外，还有很多形式。比如，有些工具自动根据代码生成接口文档。但大致上信息内容就是这些。

而接口测试报告。由于大多采用自动化测试，一般会直接用Xunit系列的报告格式。如果有特殊需求，则从这些报告里提取数据后自己生产特定格式的报告，一个xunit系列的报告长这样：

如果你是手动测，那么手动创建报告可以自己定义一个格式。实际上我曾经做过一些用了这种比较漂亮的可视化效果的报告，像这样的：

这些都好做，只要你想得出来，用简单的html+js就可以做。

首发于公众号：测试进阶(test_up)

原问题讨论来自以下付费社群，扫码即可加入。