apidoc自动生成接口文档

最近整理项目发现接口文档很零散，还不是特别准确。apidoc可以根据注释自动生成api文档，这里记录一下。

安装步骤：

1. apidoc是一个基于nodejs的API文档生成工具，先确认系统是否已安装nodejs，然后安装apidoc，执行：
   npm install -g apidoc
2. 配置apidoc，在你的项目的根目录下创建apidoc.json文件,apidoc.json说明

{
  "name": "api doc",
  "version": "0.1.0",
  "description": "interface doc",
  "title": "接口文档",
  "url" : "http://localhost:8080"
}

3.添加注释
在对应的接口的方法上添加注释。

/**
 * @api {POST} /register 注册用户
 * @apiGroup Users
 * @apiVersion 0.0.1
 * @apiDescription 用于注册用户
 * @apiParam {String} account 用户账户名 
 * @apiParam {String} password 密码
 * @apiParam {String} mobile 手机号
 * @apiParam {int} vip = 0  是否注册Vip身份 0 普通用户 1 Vip用户
 * @apiParam {String} [recommend] 邀请码
 * @apiParamExample {json} 请求样例：
 *                ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {int} code 0 代表无错误 1代表有错误
 * @apiSuccessExample {json} 返回样例:
 *                {"code":"0","msg":"注册成功"}
 */

注释含义见apidoc官方文档
@api 定义API的请求方法、路径和名字（一般是必须编写的，不然apidoc编译器会忽略这段注释）
@apiGroup 定义API的分组
@apiVersion 版本
@apiDescription 定义API的描述
@apiParam 定义API的参数
@apiParamExample 参数请求的事例
@apiErrorExample API错误示例
@apiSuccessExample API正常示例

注： @apiGroup 不支持utf-8 字符串。仅支持ascii码。所以只能用英文,如果想用中文，方法如下
代码如下

/**
 * @apiDefine user 用户接口文档 
 */
/**
 * @api {post} /user
 * @apiGroup user
*/

说明
1、@apiDefine 必须放置在 /* ……/中，也必须与引用变量的地方分开。
2、@apiGroup 后 放置的是 @apiDefine 定义的 变量名

4.生成文档
执行命令
apidoc -i com/ -o apidoc/
-i com/是把com文件夹下带有apidoc语法注释的代码全部生成文档
-o apidoc/是文档的生成目录
执行完成后打开apidoc文件夹下的index.html文件，可见到对应的api文档了

参考：
http://apidocjs.com/
https://cloud.tencent.com/developer/article/1005271
https://blog.csdn.net/soslinken/article/details/50468896