nodejs restful 的api文档生成

1、apidoc的官网

http://apidocjs.com

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文档：