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