两套系统要打通，接口文档是前提。实际项目里，接口文档常常是最后才补的，补出来的还跟实际接口对不上。对接方照着文档写，联调时发现字段名不对、参数含义不一样，来回折腾。
把接口文档当成交付物的一部分，从一开始就要求，比事后补要省事得多。
一、谁写，什么时候写
接口文档应该由提供接口的一方写，也就是服务的提供方。理由很简单，接口是他实现的，字段含义他最清楚。
写的时间点很关键。应该在开发接口的同时写，接口写完文档也就有了。等开发全部结束再回头补文档，往往记不清细节，写出来的东西跟实际实现有出入。有一种做法值得推荐，就是先定接口，双方确认之后再各自开发。这样接口在开发之前就冻结了，两边的实现都对得上。
甲方在里面的角色是把关。接口清单和关键字段要甲方确认，尤其是涉及业务含义的部分，比如状态值分别代表什么、金额是含税还是不含税。这些技术方看不出来，只有业务方知道。
二、至少要包含这些内容
接口地址和请求方式，这是最基本的。请求参数要列全，包括名称、类型、是否必填、含义、示例值。响应内容同样要列全，还要说明每种情况下的返回码含义。
出错时的返回要写清楚。对接中最耗时的往往是差错处理，如果文档里只写了成功的情况，出错时双方只能猜。建议把所有业务上的异常情况都列出返回码和含义，比如数据不存在、状态不允许、重复提交。
还要有的内容，认证方式、请求频率限制、字段长度限制、时间格式、编码方式。这几项每一条都曾在实际对接中成为卡点。比如时间格式是时间戳还是字符串，不写清楚，两边解析出来的结果能差几十年。
三、怎么保证文档和实际一致
文档写了不维护，很快就不准了。几个做法能提高一致性。
一是把文档放在能在线更新的地方，不要用离线的文档文件传来传去。文档地址固定，双方都看同一份。
二是提供可调试的环境。文档里给一个测试环境的地址和测试账号，对接方直接发请求就能看到真实返回，比看文档快。有了这个，文档的主要作用从描述接口变成了索引接口。
三是版本化。接口有变化时，新版本用新的路径或者版本号，旧版本保留一段时间。不要在原来的接口上直接改，正在对接的一方会突然收到不一样的返回。
四、甲方验收接口该看什么
甲方不需要懂技术细节，但可以看三件事。
看接口清单是否覆盖了业务需要打通的场景。比如要同步客户信息，是不是包含新增、修改、停用三种情况，只做新增是不够的。
看字段含义有没有业务方确认过的痕迹。关键业务字段，比如状态、类别、金额口径，应该有业务方的确认记录。
看有没有实际跑通。最好的验证是让对接方真的调一次，把结果给甲方看。文档写得再全，没跑通过就不算数。
上一篇软件项目为什么会越做越大