使用apidoc为你的项目编写api文档

在使用apidoc之前，我一直使用wiki来写文档，后来发现这种方式更新起来比较痛苦，时间一长甚至就忘记了更新了。一直在寻找能够使用注释直接生成文档的程序。某一天同事推荐了apidoc，发现这正是我想要的工具。

apidoc原理

apidoc的原理是扫描你的代码文件，提取出注释部分，根据一些规则生成相应的文档。默认的模板久很美观，十分适合作为api文档的生成器。目前apidoc支持的注释基本涵盖了大部分语言的风格了，c，java，php，js，python，perl，lua, Erlang…

安装

需要使用npm安装，如果没有安装npm，请先去https://www.npmjs.com/下载npm并且安装。安装之后使用如下命令安装apidoc

npm install apidoc -g

开始API文档

通常我们的api的是通过一个方法的调用，在mvc架构的c层。如果一个api是 /foo/bar ,那么可以在相关的方法调用中这样写注释

/**
 * @api {GET} /foo/bar 一个测试的接口
 * @apiName  foobar
 * @apiVersion 0.1.0
 * @apiGroup foo
 * @apiDescription 这是一个测试的接口，会输出一个hello world
 */

这样一个最简单的apidoc支持的注释就出现了，接着要做的就是将这些注释生成一袭html文档。在项目的根目录需要建立一个名字为apidoc的json文档

{
    "name": "test",
    "version": "0.1.0",
    "title": "测试项目",
    "description": "这是一个测试的项目",
    "url": "http://www.imhuchao.com"
}

这些意思都很好了解，name的意思为项目名称，version为版本号，title为项目标题，description为项目的描述，url为接口的地址。比如这里的url是http://www.imhuchao.com，上面写了一个测试接口为/foo/bar，那么生成的文档中的接口地址就会是 http://www.imhuchao.com/foo/bar。

有了apidoc.json，接下来就可以进行文档的生成了，命令为

apidoc -i [input dir] -o [output dir]

需要指定输入和输出的地址，用手敲命令执行比较麻烦，因此我一般是在项目中新建一个脚本，执行脚本就可以自动生成。比如php的可以是

$input = __DIR__;
$output = __DIR__ . '/apidoc';
$shellout = '';
exec("apidoc -f \".*\\.php$\" -i {$input} -o {$output}", $shellout); //这里只需要扫描php文件，其他的文件不生成注释
print_r($shellout);

其他的语言也类似了，或者在linux或者mac上直接使用shell脚本就可以。

关于apidoc命令的使用，可以使用apidoc -h来查看其他的参数，比如自定义模板之类的。

apidoc注释支持的标签

• @api
• @apiDefine
• @apiDeprecated
• @apiDescription
• @apiError
• @apiErrorExample
• @apiExample
• @apiGroup
• @apiHeader
• @apiHeaderExample
• @apiIgnore
• @apiName
• @apiParam
• @apiParamExample
• @apiPermission
• @apiPrivate
• @apiSampleRequest
• @apiSuccess
• @apiSuccessExample
• @apiUse
• @apiVersion

更详细的可以去 http://apidocjs.com/ 查看apidoc的使用。