nodejs restful 的api文档生成
1、apidoc的官网
2、安装nodejs环境，安装apidoc
npm install apidoc -g
3、在项目根目录创建：apidoc.json；如：
{
"name": "video-server",
"version": "1.0.0",
"description": "video-server相关API文档",
"title": "video-server API",
"url": "http://localhost:3001/api",
"sampleUrl": "http://localhost:3001/api",
"forceLanguage": "zh-cn",
"template": {
"withCompare": true,
"withGenerator": true
}
}
4、public目录下新建文件夹apidoc，用于存放APIDOC生成的文件，app.js添加一句话：（我使用koa2）
app.use(require('koa-static')(__dirname + '/public'))
5、在对应的接口上添加注释，可参考下边的配置：
/**
* 获取历史视频列表
* @api {post} /getfiles 获取历史视频列表
* @apiDescription 根据通道、日期信息获取历史视频列表
* @apiName getfiles
* @apiParam {String} channelid 通道号
* @apiParam {String} date 日期
* @apiSuccessExample {json} Success-Response:
* {
* "status": "success",
* "files":
* [
* {
* "filepath":"/rec/channel1/2018-12-19_12-12-12.mp4",
* "filename":"2018-12-19 12:12:12.mp4",
* "filesize":"440MB"
* }
* ]
* }
* @apiErrorExample {json} Error-Response:
* {
* "status": "failed",
* }
* @apiVersion 1.0.0
*/
6、生成API文档
apidoc -i routes/ -o public/apidoc
7、index.js 增加如下内容：
router.get('/apidoc', function (req, res, next) {
res.type('text/html')
res.sendfile('public/apidoc/index.html');
});
8、启动项目，访问http://localhost:3000/apidoc/index.html，就可以看到生成的api文档：
