使用apidoc生成接口文档

一、首先安装node.js

1. 下载Node.js官方Windows版程序：

   https://nodejs.org/download/

   从0.6.1开始，Node.js在Windows平台上提供了两种安装方式，一是.MSI安装文件，另外还有一个.EXE可执行文件。

   我选择了.EXE文件。因为.MSI安装文件除了将node.exe复制到C:\Program File (x86)\目录中及修改系统Path之外，没发现还有其他作用。

   我使用的版本为v0.12.5: https://nodejs.org/dist/v0.12.5/node.exe


 


2、双击node.exe安装：









next之后安装完成

 

3. 下载npm源代码：

   https://github.com/isaacs/npm/tags

   这里需要注意一下，不一定要安装最新版本，我选择的是2.9.1，但是一定要下载zip这个格式的文件

   


 


4. 将npm源代码解压到D:\npmjs目录中。

   在命令提示符窗口中执行下面的操作，完成npm的安装：

D:\>cd npmjs
D:\npmjs>node cli.js install -gf

   另外：

node cli.js install npm -gf //可以安装最新版的NPM
node cli.js install npm@2.9.1 -gf //可以安装指定版本的NPM

   上面两种方法都是通过网络从代码库中下载并安装，但是代码库一般只保留最近的两个版本。

 5、安装apidocjs

npm install apidoc -g

6. 安装express：

npm install express -g //安装最新版express
npm install express@2.5.0 //安装指定版本express

npm remove express -g //删除express

   更多npm使用方法，请参考npm官方网站：http://npmjs.org

 

至此部署完成。

D:\>node -v
v0.6.2

D:\>npm -v
1.0.104

D:\>express -v
2.5.1

D:\>express hello //创建exrpess项目
D:\>cd hello
D:\hello>node app.js //启动

二、引入apidoc.json（基础配置文件）

内容举例：

{

  "name": "xxxx",

  "version": "1.1.0",

  "description": "xxxx",

  "title": "xxxx",

  "url" : "http://ip:端口/test/"

}

三、代码使用apidoc注释，如：

/**
* @api {post} /app/seatReserve/list 获取我的预定记录
* @apiName 获取我的预定记录
* @apiVersion 1.1.0
* @apiDescription 获取我的预定记录必须登录
* @apiGroup dingzuo
* 
* @apiRequest 请求参数
* @apiParam {String} token 登录token
* @apiParam {int} pageNo 页码
* @apiParam {int} pageSize 每页几条
* 
* @apiExample 请求成功数据
* {
*    "status": "1",
* "data": {
* "first": 1,
* "last": 3,
* "result": [
*            {
*                "id": 36,
*                "type": 0,
*              "createTime": 1489465078000,
*                "reverseDate": 1489420800000,
*                "startStationId": 25,
*                "endStationId": 36,
*                "sendOffTime": "13:00",
*                "nickName": "17750278741",
*                "isUse": "3",
*                "startStationName": "同济大学嘉定校区",
*                "endSatationName": "虹桥火车站P9停车场",
*                "userId": 490,
*                "routeName": "汽车城---虹桥枢纽专线",
*                "orderId": 23,
*                "routeCode": "HQ1300",
*                "routeSeq": "21",
*                "vehicleNo": "沪DJ0047",
*                "payType": 1,
*                "payment": 1,
*                "mobile": "17750278741",
*                "seatCode": "1A",
*                "shiftId": null,
*                "reverseDateStr": "2017-03-14"
*            }
*        ],
*        "totalPages": 1,
*        "hasNext": false,
*        "nextPage": 1,
*        "hasPre": false,
*        "prePage": 1,
*        "pageSize": 10,
*        "pageNo": 1,
*        "totalCount": 3
*    },
*    "msg": "操作成功"
* }
*
* 
* @apiSuccess {int} id 主键
* @apiSuccess {int} type 类型 0：上行 1：下行
* @apiSuccess {date} createTime 预定时间
* @apiSuccess {date} reverseDate 预约日期
* @apiSuccess {string} nickName 用户名
* @apiSuccess {string} isUse 是否使用 0：未使用 1：已使用 2：已取消  3已过期
* @apiSuccess {String} startStationName 起始站点名称
* @apiSuccess {string} endSatationName 结束站点名称
* @apiSuccess {int} userId 用户id
* @apiSuccess {string} routeName 线路名称
* @apiSuccess {int} orderId 订单id
* @apiSuccess {string} routeCode 航班号
* @apiSuccess {string} routeSeq 线路序号
* @apiSuccess {string} vehicleNo 车牌号
* @apiSuccess {int} payType 预定类型 0 年卡 1单程
* @apiSuccess {String} mobile 手机号
* @apiSuccess {String} seatCode 座位号
* @apiSuccess {String} reverseDateStr 格式化后预约日期
*/

四、打开cmd，开始生成接口文档：

cmd-->指到工程工作空间-->apidoc -i 工程名/ -o
工程名/apidoc（这里生成的文档放到工程目录下）