有青岛的老板问我，接口做完都跑起来了，还写文档干嘛？我的答案是：接口没文档，就像机器没说明书，平时没事，一换人、一出问题就抓瞎。信服无限青岛团队做接口开发时，最怕客户说文档等忙完再补，然后就没有然后了。
文档要写清楚怎么用
接口传什么、返回什么、出错了报什么，都得写明白。没文档，调用的人只能靠猜。青岛不少公司的接口是开发凭记忆维护的，人一休假，别人想调一下接口，问谁谁都说不清，只能翻代码，一翻就是大半天。
文档还得带上示例。青岛做接口的都清楚，一段能直接抄的请求示例，比十页说明都管用。调用方照着示例改改就能跑通，省下的沟通时间不可估量，也少了很多因为理解偏差搞出来的低级错误。
文档要给接手的人看
写文档不是为了交差，是给下一个接手的人看的。把自己当成完全不懂的新人，就写得清了。青岛不少公司的文档满是内部黑话，只有原作者看得懂，接手的同事越看越懵，到头来还是要抓着作者问，文档等于没写。
文档还要写清边界和坑。青岛做接口的，会特别注明哪些参数是必填、哪些场景会超时、异常怎么重试。这些踩过的坑写进去，后来的人就不用一个个再踩一遍，团队整体效率就是这么一点点高起来的。
文档要跟着接口维护
接口改了文档不改，比没文档还坑人。两边一脱节，照着文档调反而出错。青岛不少公司的接口悄悄加了个字段、换了个规则，文档还停在半年前，调用方照旧文档走，出了错还以为是自己的问题，排查半天。
维护要和开发绑在一起。信服无限累计上线 300+ 小程序，做这类接口开发的服务有经验。接口一改，文档同步改，当成流程的一部分，别指望谁事后想起来补。守住这条，文档才一直是可信的。
接口文档的常见疑问
接口文档要写多细
关键是把调用方式、字段含义和异常说清，配示例，够接手的人直接上手即可。
文档放在哪好
找个大家都能访问、能随时更新的地方，别只存在某个开发的本机。
文档做扎实，换人不抓瞎
把用法写清、站在接手人角度写、跟着接口一起维护，文档才真有用。信服无限青岛团队做接口时，最在意文档别人看不看得懂。你要在青岛，找一段最近做的接口，看看没有文档能不能说清它怎么用。