apidoc 文档

安装nodejs

# node -v //查看是否安装nodejs

ubuntu 安装nodejs

# sudo apt-get install nodejs  //无node的版本号就安装nodejs

centos安装nodejs

wget http://nodejs.org/dist/v0.10.24/node-v0.10.24.tar.gz

解压源码

# tar zxvf node-v0.10.24.tar.gz

编译安装

cd node-v0.10.24
./configure --prefix=/usr/local/node/0.10.24
make
make install

配置NODE_HOME，进入profile编辑环境变量

vim /etc/profile

设置nodejs环境变量，在 export PATH USER LOGNAME MAIL HOSTNAME HISTSIZE HISTCONTROL 一行的上面添加如下内容:

    #set for nodejs
    export NODE_HOME=/usr/local/node/0.10.24
    export PATH=$NODE_HOME/bin:$PATH
    # :wq保存并退出，编译/etc/profile 使配置生效
    # source /etc/profile

验证是否安装配置成功

# node -v

安装apidoc

ubuntu 安装

# npm install apidoc -g  //如果提示npm没有安装就执行下面的命令
# apt-get install npm

contos 安装

tips: npm 是在你安装的node目录下 [下面是我的node目录]
/usr/local/nodejs/bin/npm install apidoc -g 

apidoc 操作语法

# apidoc -i test/ -o test/apidoc/     //基本用法

参数

 -f, --文件过滤器    选择什么格式文件被解析. 默认有 .cs .dart .erl .go .java .js .php .py .rb .ts.
Example :
    apidoc -f ".*\\.js$" -f ".*\\.ts$"

-i, --文件输入 你的项目文件.
Example:
    apidoc -i myapp/

-o, --输出目录  生成文档的位置.
Example:
    apidoc -o apidoc/

-t, --指定模板  使用模板输出.
Example:
    apidoc -t mytemplate/

---

对比下面的两个例子，对apidoc的文档参数就有个基本认识了

例子 01

/**
* @api {get} index.php?i=  测试一
* @apiGroup test
* @apiVersion 0.0.1
* @apiDescription 这是第一个测试
* @apiParam {String} token 登录token
* @apiParamExample 请求样例
* /index.php?i=8888
*  @apiSuccess {int} type 类型 0：上行 1：下行
* @apiExample 请求成功数据
* {
*    "status": "1",
*    "data": {
*               "first": 1,
*               "last": 3,
*    },
*    "msg": "操作成功"
* } 
* @apiExample {json} 失败返回样例:
*     {"code":"0","msg":"修改成功"}
*/

例子02

/**
    * @api {POST} /test/:id 测试二
    * @apiGroup test
    * @apiVersion 0.0.1
    * @apiDescription 这是第二个测试
    * @apiParam  {String} name 名字
    * @apiParam  {String} [phone] 手机
    * @apiSuccess (Success) {String} msg 信息
    * @apiSuccess (Success) {int} code 0 代表无错误 1代表有错误
    * @apiError (Error) {String} msg 信息
    * @apiError (Error) {String} m 信息
    * @apiParamExample 请求样例
    * /index.php?i=8888
    * @apiSuccessExample {json} 返回样例
    *                {"code":"0","msg":"修改成功"}
    * @apiErrorExample {json} 失败返回样例
    *                {"code":"0","msg":"修改成功"}
*/

apidoc 文档参数详细说明

* @apiDeprecated [提示消息] //弃用标志 如果未指定[]里面内容{包括中括号}，则下次不产生该接口，如果指定，则输出提示消息
* @api {POST} /test/:id 测试二 //指定接收方式以及显示名称
* @apiGroup //分组
* @apiVersion //版本
* @apiDescription //描述
* @apiParam  {String} name 名字 // 参数类型 以及参数名称 没有中括号代表必选参数
* @apiParam  {String} [phone] 手机 // 参数类型 以及参数名称 [phone] 代表可选参数
* @apiSuccess (Success) {String} msg 信息 //返回成功数据名称以及类型
* @apiError (Error) {String} msg 信息 //返回失败数据名称以及类型
* @apiParamExample 请求样例  //示例
* /index.php?i=8888        //例子
* @apiSuccessExample {json} 返回样例  // 返回成功数据以及指定返回数据格式
*                {"code":"0","msg":"修改成功"} //指定json格式后可以不用格式化，apidoc 输出的时候会做做处理
* @apiErrorExample {json} 失败返回样例 // 返回失败数据以及指定返回数据格式
*                {"code":"0","msg":"修改成功"}

tips

01： warn: Please create an apidoc.json configuration file.

检查你的项目下 有没有 apidoc.json  //没有则创建
{
  "name": "文档名称",
  "version": "0.1.0", //版本号
  "description": "apiDoc basic example", // 描述
  "title": "Custom apiDoc browser title", // 头部
  "url" : "http://192.168.197.135/"  // 项目地址
  "sampleUrl" : "http://192.168.197.135/"  //接口默认发送的地址
}

02：warn: parser plugin ‘param’ not found in block: 1

具体问题没有找到 下面的是我的做法
# rm -rf test/apidoc/*
# apidoc -i test/ -o test/apidoc/
-- 这样子就解决了！

03 :apidoc error: No files found. { Path: ‘/data/wwwroot’ }

应该是因为 nodejs版本太高 以及 npn版本太高的原因