身为措施员最讨厌看到的代码没有注释，本身的代码却讨厌写注释，感受麻烦，接口也是这样。
好比公司要做一个H5勾当的页面，开发文档已经发到后端开发、设计、与前真个邮箱了，其实这个时候就可以开始开发了。开发人员开始论证H5页面中逻辑是否能够实现，以及该逻辑的合理性，及时的反馈给产品进行改削或者优化。等一切都定下来的时候，各方面就可以开始动工了。
一般来说，设计资源会在后端接口开发完成之前给到。对付一个对开发事情足够得心应手的后端工程师，一般看到设计稿，就知道接口的数据布局和内部的逻辑是怎么样的。因此不必等到接口真正开发完成，才给到前端同学。
这样子前端同学和后端同学，均能并行开发。好比一个H5勾当页面需要本来需要1个星期来完成，此刻只需要4天时间，节省的两天，措施员就可以用来提升本身技能和用来休息了。
但是呢，人都是惰性的。开发的时候不愿意写文档，尤其是接口文档，感受很麻烦。我的同事们，有时候也懒得写接口文档，，前端同学按照接口返回的数据来进行开发，有时候接口返回数据堕落，前端并不知道正确的接口数据是什么，就会产生迟误开发时间，原来能够如期完成事情，功效在对接接口方面花费了太多的时间。
在大量的接口开发事情中，我使用了很多文档工具，如Markdown 工具（马克飞象），此外一个就是ApiDoc文档生成工具。markdown 语法大部分写过措施的同学都知道，对照好用，适合写个博客什么的，可以把写作的焦点放在内容上，而不是格局上。但是对付markdown 写的接口文档来讲，可能就不太适用了。接口文档需要丰富的格局来构建条理，还需要表格来装载参数。当接口很多的时候，还需要将接口分类，还需要有检索接口的成果。此外一个痛点就是，好比后端PHP开发同学写了个markdown文档，给到了前端同学，或者客户端同学，还要提示他们如何使用。并不是每小我私家电脑都装了markdown解析器。这样子就很烦人了，还好ApiDoc 解决了这个棘手的问题。
用了很永劫间，总结了ApiDoc 的几个长处：
1、安置简便，傻瓜式安置
2、接口文档语法很简单，不必增加记忆本钱，写接口文档很轻松，不再耗费大量时间，而是顺手复制粘贴
3、生成的文档格局标致，并且实用，满足了开发人员对接口的各类需求。
由于本文并不是讲述ApiDoc 的教程文档，说实在话，这类对象，还是官方的文档最实用。参数那么多，并不需要拿个小本本记下来，需要的时候，到官网上复制粘贴即可，用多了，自然常用的就会记下来。附一张ApiDoc 生成文档的截图：