邯郸公司做接口开发，文档别等出事才补
邯郸这边的企业问我最多的，就是这一条，接口文档要不要花时间写？先说结论：要，而且要开发同步写。事后补文档，补出来的都是残缺的。等到换人接手或者改需求，缺的那部分就要花十倍时间找回来。我们做项目按 Scrum 迭代，每 2 周交付一个可用版本。
文档至少要写清这四块
地址、参数、返回值、错误码。前三个决定别人能不能调通，第四个决定出问题能不能查。参数要写清类型和是否必填，返回值要给出示例。峰峰有家公司接口调不通，查了两天，后来发现是必填字段漏了一个。文档写全，就是省这种时间。
错误码最容易被凑数。错误码要能区分是参数错、还是对方系统错。都返回一个 500，排查只能靠猜。我们做接口开发时会按类别分层，参数类、权限类、业务类各有区分。涉县有家门店靠分层错误码，把排查时间从半天压到十分钟。清晰一点，省很多事。
文档要有人看，也要能更新
写完塞进文档库没人看，等于没写。建议放到接口调用方能随手查到的地方，并留一份联系方式。改动要及时同步，尤其是字段含义和必填项的变化。我们做交付时会把文档链接写进项目验收清单。复兴区一家厂子每次改接口都在群里同步一句，对方就很少踩坑。同步一句话，省一通电话。
版本和兼容要提前想
接口改动最容易伤到已经在用的调用方。新增字段一般安全，删字段和改类型最危险。要改就先加新版本，老版本保留一段时间。我们做接口时会从 v1 开始留好版本位。曲周有家商户提前留了版本路径，改字段时对方系统没受任何影响。留一手，后面就不慌。
常见问题
接口文档应该谁来写
建议由开发同步撰写，产品或者项目经理核对业务含义。不要等项目结束再补。
接口改了怎么通知对方
提前发变更说明，写清影响的字段和时间点。重要变更建议电话确认一次。
文档放在哪里比较好
放在调用方能直接访问的地方，比如内网文档站或者协作工具的接口模块。
邯郸的公司做接口，把文档和开发一起做，别攒到收尾才补。文档是给未来的自己和同事看的。你说一下现在有几个接口在跑、有没有文档。剩下的细节，信服无限邯郸能按你的实际规模来配。