联调现场经常出现这样的场景：前端同事按接口文档写完了页面，一对接就频繁报错，查了半天发现文档里只写了成功时返回什么，失败时返回什么、字段能不能为空、长度超了怎么处理，全都没有交代。问题不在代码能力，而在文档只描述了顺利路径，把大量真实情况留给了联调现场去猜。
接口文档缺失的信息通常集中在几类。一是错误码与错误结构，只写成功码等于没写异常处理依据，前端无法判断该提示用户还是该重试。二是必填与选填边界，哪些字段不传会报错，哪些可以不传，必须逐项标明。三是字段类型与长度，字符串最大多少字符、数字是否允许小数、时间用什么格式，都要写清楚。四是空值与默认值，字段为空时返回空字符串、null还是省略该字段，三种情况前端处理方式完全不同。五是分页与排序约定，页码从几开始、每页上限多少、默认按什么排序，不写清楚就会出现翻页重复或漏数据。
补齐时可以按调用顺序列清单。请求前，确认地址、方法、鉴权方式和公共请求头；请求中，逐字段核对名称、类型、是否必填、长度范围和示例值；成功响应，写清外层结构和每个业务字段的含义；失败响应，列出主要错误码、对应含义和建议处理方式；超时与重试，说明超时时间、是否允许重复提交、重复请求如何识别。这份清单不需要多复杂，关键是每一项都有明确答案，而不是“视情况而定”。
更实用的做法是做一张对照表，左边写“文档当前写了什么”，右边写“联调实际需要什么”，逐项比对。比如文档写了“返回用户信息”，联调需要知道手机号是否脱敏、昵称超长是否截断；文档写了“操作成功”，联调需要知道失败时前端拿什么字段做提示。比对完成后，缺口一目了然，补文档也有了优先级。
文档变更同样需要约定。口头说一句“这个字段改了”最容易埋雷，应当要求每次调整都落到文档里，标注修改日期、修改人和影响范围，接口地址或字段含义发生不兼容变化时单独说明。版本记录不必复杂，但要能让人回查到某次联调时依据的是哪一版约定。
接口文档的质量直接影响交付效率，写得清楚，联调和测试就能少走弯路。it数运在软件开发协作中，把接口约定当作可核对资料的一部分，需求、字段和异常处理都尽量落到书面，让前后端对接有据可查。文档不是写给检查看的，而是写给下一个要调用它的人看的。
