最近对接了几个测试管理平台的接口文档，自己也更新了DCS_FunTester分布式性能测试框架的接口文档，总地来说，感触良多。
首先我个人工作经验最大的一个感触就是。如果说一件事情做好，能够最大的提升工作效率，我觉得就是文档规范。对于接口测试来说，接口文档。就是最要命的卡脖子技术。特别是今天接触 jira 的 api 接口文档，让我有了想砸键盘的冲动。
那么今天我分享一下我自己对一个合格和优秀的接口文档的认识。这里我认为的合格接口文档就是本分，优秀的接口文档就是卓越。
合格
项目部分
首先，合格的接口文档必须包含以下几种要素。首先是要对项目进行介绍。除去业务支持的简单介绍以外，还必须对项目的环境和 host 它的对应关系、项目所涉及到的请求方式、各个请求方式的传参格式、以及项目规定的请求头内容。包括不限于项目中所遇到的加密解密算法以及多语言实现 Demo。这些都要给出详细的说明。
对于一个项目来说，接口肯定会比较多，甚至上百上千都有可能。这就要求接口文档。必须进行模块化划分。第一次为了阅读和编写的时候的方便地儿，也是能为了能够更好的管理接口文档。不同模块划分要有一定的标准，而且这个标准要和接口的 url 统一。这个必须是强标准，不能存在差不多、可能、就这样这种词汇。
模块的划分要与模块下面的接口有很强的关联性。特别是在 url 的划分上。因为在测试的过程中，我们基本不会再去翻回头看接口文档。如果能通过 url 判断这个接口所在的模块以及这个接口的功能，那对于测试来说是一件极其幸福的事情。
接口部分
在接口部分，接口文档的格式会比较统一。一般也必须包含以下几种要素。第一种是请求（非参数），第二种是请求参数，第三种就是请求的响应结果。
对于请求非参数的数据一般包含以下几个方面。第一就是请求的地址。第二次请求的方法。第三是接口的业务。PS：最好写上开发名字。
对于请求的参数。一般包含几下几项。要素第一就是参数的整体格式。参数名、参数值、关于参数值的话，一定要说清楚参数的范围、校验的规则。
对于接口响应。一般包含以下几项要素，第一就是响应的 demo。想用中异常情况的处理。这个异常情况包含了 http 响应异常以及业务响应异常，特别是业务响应异常中必须要包含业务响应的 code 以及业务响应 code 所对应的业务场景。
维护
对于测试人来而言，接口文档未能及时的更新，是导致测试用例执行失败的重要原因。所以在进行接口测试之前，一定要确保接口文档的准确性。在一些场景下，接口文档是需要人手动去维护的，而手动维护就带来两个问题。第一个问题就是手动维护所带来的错误，第二个问题是手动维护所带来的延迟。要解决这两个问题，方法是多种多样的，既有从技术方面的，也有从管理方面的，还有从跨部门协调方面的，这个大家可以在网上搜一搜。合格的接口文档。需要在提测之前保证接口文档的准确性实时性。以及在这提测的过程中，及时的修改和维护相关文档。以及通知到相关测试人。
如果发生接口，文档必须有所更改的场景。那么就非常的考验这个接口的设计者。
优秀
项目部分
首先，优秀的接口文档在合格的接口文档上最显著的一个特征就是在描述几种项目必须要素基础上。要给出更加详细的说明以及所涉及到的技术细节。甚至要给出关键代码逻辑的 demo。例如，除了文字版叙述加密，解密和验证算法以外。要给出测试语言所能够时直接抄用的代码 demo。
在项目所涉及到的请求方法这个要素上，要给出更加详细的方法使用规范。在传参格式这个要素上，要给出传参的具体请求和响应内容的 Demo。虽然项目中总有一些特殊的接口会违反这些规范，有的时候也是不可避免的。特别是在跟二方系统三方系统对接的时候，很难做到全部统一。但是还是需要开发，在编写文档的时候，给出一个统一的格式。这样能够极大的减少测试人员的工时消耗。
针对一个优秀的接口文档。给人最直观的观感就是它的目录部分。这部分包含着整个项目结构文档的功能模块集合。要让人看了接口文档，对整个项目的业务功能有一目了然之感。而且接口文档模块儿。要有足够的文字说明。模块的划分要与模块下面的接口有很强的关联性。特别是在 url 的划分上。我认为优秀的接口文档的一个重要体现就是测试人员拿到一个接口的地址，然后能在这个接口文档的成绩目录中找到这个接口准确的位置，而不是通过全局搜索才行。
接口部分
对于优秀的接口文档来说，接口部分，除了以上的。几个要素以外，还需要对接口请求参数的。参数名进行文字说明，因为有时候如果参数特别复杂的话，是不太能够看清楚参数名，得到参数业务的相关情况的。这里我遇到的方法有两大类。一类是在定义参数。名称的时候有一定的统一规范。且全局对于同一业务使用同一的英文单词。对于相同业务的行为进行统一的命名规范。例如添加用户这个接口，就需要用 adduser。而不能使用 at customer 或者 insertuser 这样的词汇。以免造成同一业务逻辑在不同的接口有不同的名字。
优秀的接口文档，另外一个最大的体现就是让测试人员在简单阅读接口文档之后，能够迅速的调通这个接口。依赖于接口文档中给出的请求参数的 demo。这对测试人员来说非常重要，因为如果一个接口请求不通的话，原因可能是多个因素叠加在一起的。测试人员很难在接手一个新接口的时候，就把这些因素区分开。所以就需要一个正确的请求参数组合来帮助测试人员迅速的调试通过接口。
除了以上几个方面以外，我觉得还有一个对我来说非常重要的接口测试文档，内容就是参数来源。因为在我实际做测试的过程当中，大多数的接口参数都是从另外的接口响应中获取的。一般规定的接口的范围可能是 1~1 万这样子，但是对于我要测的业务来讲，只可能就是几个。正常，我们会对接口先进行接口参数验证的验证，也就是冒烟测试。但是越过这个阶段之后 d，我们需要进行更多的是业务相关的一个接口，测试文档参数以及响应数据来源，一般都是需要跟其他业务相关的接口有关联性的。接口测试不像一位车手可以通过页面去查看相关的。内容。接口测试面对的就是一堆 json 数据。如果接口的参数命名不够统一，不够规范的话。接口，测试人员很难去找到业务测试中接口数据的验证值。所以我认为接口测试参数来源非常重要。同样的。响应数据的。也非常重要
维护
对于优秀的接口文档而言。接口文档的实时性和准确性已经得到了保证。需要提高的就是文档变更的次数减少以及变更时的人员通知。如果是新街口的话。第一次提测过程当中，接口文档的变更是非常难以避免的。这里测试人员要有心理准备。但是对于旧接口，维护和更新是低频率发生的事情，但是一旦发生处理不及时，就会导致一些故障。
最好的接口文档就是一次编写，永不维护的。
当然这是不太可能的。
优秀的接口文档，关键不在于文档本身。而在于开发，测试相互的沟通渠道以及沟通效率。
反面教材
下面我复制了一下 jira 的接口文档中创建 issue 的方法。啊首先要说一下 jira 的文档写的还是非常好的，虽然是英文的，但是通过翻译软件翻译出来阅读也是没有任何障碍的，但是我要吐槽的就是他关于接口参数以及接口响应的处理。
在下面这个例子中，jira 官方给出来的一个请求的 demo，但是在实际测试过程中啊，参数最外层的 update 完全不需要。我也没搞清楚他放在这里的具体含义是什么。还有就是呃关于 fields 里面参数 values 的传参方式：这里要吐槽的两个点第一个就是明明传一个值来解决的非要穿一个 JSON 对象。第二个就是把数字也当做字符串来处理了，不仅如此啊，包括日期型的数据，它也是当做字符串来处理的。
创建问题
POST /rest/api/2/issue
可以使用/rest/api/2/issue/createmeta资源确定可以在创建时在 fields 参数或更新参数中设置的字段。
例子
{
"update": {
"worklog": [
{
"add": {
"timeSpent": "60m",
"started": "2011-07-05T11:05:00.000+0000"
}
}
]
},
"fields": {
"project": {
"id": "10000"
},
"summary": "something's wrong",
"issuetype": {
"id": "10000"
},
"labels": [
"bugfix",
"blitz_test"
],
"timetracking": {
"originalEstimate": "10",
"remainingEstimate": "5"
},
"security": {
"id": "10000"
},
"versions": [
{
"id": "10000"
}
],
"environment": "environment",
"description": "description",
"duedate": "2011-03-11",
"fixVersions": [
{
"id": "10001"
}
],
"components": [
{
"id": "10000"
}
],
"customfield_30000": [
"10000",
"10002"
],
"customfield_80000": {
"value": "red"
},
"customfield_20000": "06/Jul/11 3:25 PM",
"customfield_40000": "this is a text field",
"customfield_70000": [
"jira-administrators",
"jira-software-users"
],
"customfield_60000": "jira-software-users",
"customfield_50000": "this is a text area. big text.",
"customfield_10000": "09/Jun/81"
}
}
状态 400如果输入无效（例如缺少必填字段、无效字段值等），则返回。
例子
{
"errorMessages": [
"Field 'priority' is required"
],
"errors": {}
}