接口文档编写规范与联调问题记录方法.docx

接口文档编写规范与联调问题记录方法

接口文档的定位与读者

接口文档是系统之间对话的说明书，写给调用方的开发看，判据是不用问原作者就能正确调用。××要求文档自解释，读一处接口就能知道怎么请求、返回什么、错了怎么办，缺1项就得多开1次沟通。

好文档追求一次读懂。××见过字段说明含糊、示例缺失的接口，联调方反复试探、约浪费2个人日。规范接口以真实、准确、示例齐全为底线，文档与代码同步更新、不许落后于实现。

文档要能版本演进。××给每个接口挂版本、记录变更历史，向后兼容的改动约保留2个版本，调用方按版本查对应说明，不会因升级而找不到旧规则。

文档要素

必备

更新时机

评审次数

责任人

基本信息

是

新