开发的接口人走了，新来的对着代码猜半个月，这种事广州不少公司都碰过。接口文档和代码一样是交付物，不能等出事才补。换个人接手，不该像重新做一遍。
文档要写清这几样
地址和参数、返回和错误码，四样缺一不可。我们给客户做开发，文档和代码同仓管理，常斌常打比方：源码就是产权归属的凭证，文档就是使用说明书，两样都得交。经手的小程序超过三百个都这么执行，从没含糊过，缺一样都不算交付完成，这是底线。
改代码必须顺手改文档
最容易烂的就是这里，谁改接口谁补文档。我们做不留代码尾巴，验收全交，附一年维护，文档也作为一部分交付，后续维护的人能直接看，不用翻聊天记录猜，猜错了生产环境就出事故，客户直接投诉，老板的脸面也挂不住。
给接口做个示例
光写字段名不够，给一段真实请求和返回。我们服务过的客户，有示例的接口，对接方当天就能联调；没示例的，来回问一周，工期就这么拖没了，老板还以为开发在认真干活，其实卡在等一个样例，白白耗着人力成本。
广州公司做接口开发，文档和代码一起交付。参数和返回、错误码和示例都写清楚，换个人接手当天就能联调，不用对着代码猜半个月。
常见问题
文档用什么格式好
能在线看、能导出的都行。广州信服无限交付时，会把接口文档整理成可检索的文件，随源码一起交给客户，谁要用都能马上翻到，不用在群里喊谁有那份文档，喊半天没人理，耽误的都是自己的事。
老接口没文档怎么补
对着现网抓包反推，再让开发确认。我们建议补完先给一两个调用方试用，验证无误再归档，别关起门来写错还不知道，写错了下游全跟着错，连锁反应最头疼，排查起来比重写还累，不如一次写对。
文档要更新到什么程度
每次上线同步更新即可。服务过的合作企业一百六十余家，靠这习惯把接口维护成本降了下来，新人不背旧债，交接也痛快，不像某些公司交接全靠老人口述，人一走全断，新来的只能从头摸。
绕不开的这几样
往简单讲，文档写清四样、随代码更新和配真实示例。你把现有接口列个表，我们帮你补一份能直接用的文档。