用apidoc生成webAPI文档

经历了多次尝试，终于找到满意的webAPI生成工具了

起初了解到生成API文档工具有jsdoc、YUI、jsduck，最后选择jsduck来试验，原因有：

1.与jsdoc相比，jsduck对注释格式要求较宽容，即使注释不符合要求，也可以生成文档。
2.jsduck生成的文档，可以查看源码。
可看这篇文档给出的对比分析：
Javascript自动化文档工具：YUI Doc, JSDoc 3, JSDuck等比较
试验结果是jsduck生成的文档层级目录很清晰，但是它不支持函数名显示中文（jsdoc也这样），API多时，不利于新手查阅。下面是官网的文档风格：

jsduck使用ruby语言开发，我不懂ruby，只为了改源码还要学一下ruby，掐指一算不划算。这个时候就遇见了apidoc官网在此， apidoc在node工程下可以直接使用，生成的文档上函数名有中文说，会让人更加易懂。而且apidoc的注释风格和jsduck很像，所以替换起来也比较方便。
不过apidoc显示的apiGroup名字不支持特殊字符，因为它把apiGroup值作为页面标签的id，所以我修改了apidoc源码，现在可以支持显示特殊字符了。
举个例子：

/**
* @apiExample 用法示例
* Person.Util.number.format(123456);//"123,456"
* @apiExample 功能
*1.将传参n转化为整形数据，有小数点的舍弃小数点，再转换为string类型。
*2.每3位加1个逗号
* @apiNameformat* @apiGroup Person.Util.number
* @api {~} Person.Util.number.format 格式化数值format
* @apiParam{object}n 需要处理的数值 类型：string， Number
* @apiSuccess (return){string}str 格式化后的数值
* @apiVersion2.1.0
*/

效果：

image.png

apidoc的安装很简单，全局安装命令:
tnpminstall apidoc -g
运行命令就可以执行：
apidoc -imyapp/ -o apidoc/
myapp是源码目录，apidoc是目标文件目录。很容易集成到gulp任务中。
注释标签说明可以参考apidoc官网，这里介绍几个常用的标签：

@apiGroup: 定义函数的分组。把apiGroup值作为页面标签的id，假设值为GY.Util.number，生成的api_data.js文件中group是'GY_Util_number-format'，apidoc本身是直接用group的值显示在页面上的。经修改过的apidoc，会将开发者写入的apiGroup值显示在页面。
@apiExmple: 用来写示例，介绍的。多个apiExmple会在页面形成一列tab标签，查看很方便。
@apiSuccess： 成功的返回字段，书写格式@apiSuccess (group) {type} filed description
group如果不填写默认是Success 200，如果API不需要请求ajax，这里最好不用默认值，可以写成return等。
@apiParam ： 参数描述，通过{type=allowedValues}可以列举参数取值范围。

其它描述参考官网。