API文档自动生成工具：apiDoc

序言

对于一个后台的开发人员来说，API 文档可谓是与前端开发者沟通交流的桥梁，重要性不言而喻。然而，很多的程序员对写文档这种事心里上是很抗拒的，究其原因的话，我想一方面在于写出来的 API 文档是有一定的美观性要求，另一方面，当程序的接口或数据不断调整时 API 文档必然要随之修改，这样来来回回既花费了大量的时间又挺折腾人。

其实每一个优秀的码员在自己的代码中都会加上相应的注释，如果我们能够直接从代码的注释部分自动解析并生成对应的 API 文档，这可就大大提高了我们的效率并且为自动化提供了可能，下面就介绍一款 API 文档自动生成的小工具 「 apiDoc 」。

简介

apiDoc 支持的编程语言非常非常多，包括 Javascript , Java , Go , PHP , C# , Python , Ruby , CoffeeScript , TypeScript 等等等等，其工作原理也很简单，按照约定的方式在代码中编写 API 相关注释，它便会从注释中解析各个参数最后生成 API 文档。

使用

安装：

npm install apidoc -g

以下是官网的一个简单的示例：

注释部分以两个 * 号开始，所有参数均以 @ 开头：

• @api 指定请求的方法 、URL 、说明
• @apiName API名称
• @apiGroup API分组
• @apiParam 参数类型、参数名、参数说明
• @apiSuccess 请求成功返回的参数类型、参数名、参数说明
• @apiSuccessExample 请求成功的示例
• @apiError 请求错误名称、错误描述
• @apiErrorExample 请求错误示例

以上一个简单的例子可谓是包含了一个 API 文档所有的基本项。

命令行输入以下指令自动生成 API 文档：

apidoc -i <输入文件位置> -o <输出文件位置>

再来看看上面这个例子自动生成的 API 文档的最终效果图：

图片太大分开截的图，拼接的不好凑合看吧。。不过怎么样，最终自动生成的 API 文档是不是很简洁优雅！另外说明一下，自动生成的其实是包括字体、css 样式在内的静态文件（使用默认模板即可，不需要自己配置），当然还有 index.html（在浏览器中预览此文件就是上图的效果）。

结束

简单的介绍就这样吧，本文的目的纯粹就是推荐一下 apidoc 这个小工具，让我们更快速高效的产出 API 文档 ，至于 apidoc 的更多更详细的用法，参考官网即可（npm 或 github 上搜索 apidoc 第一个就是的），官网的介绍真的真的真的很好，你肯定看得懂。