Nodejs 使用 apidoc生成Restfull API 文档

工具名称：apiDoc Git地址：https://github.com/apidoc/apidoc 项目地址：http://apidocjs.com/

1. 安装apiDoc

npm install apidoc -g

参数说明： -f 文件过滤 使用正则表达式，表示哪些文件需要本转换，不设置的情况下，默认为.cs .dart .erl .go .java .js .php .py .rb .ts 后缀的文件。

-i 代码文件夹

-o 输出Api文档的路径

-t 使用模板文件的路径，可以自定义输出的模板

2. 配置 apidoc.json

无package.json文件时，需要在代码文件夹的根目录下，创建apidoc.json文件。

{ "name": "Apidoc Example", "version": "1.0.0", "description": "Apidoc Example descrption", "title": "Custom apiDoc browser title", "url" : "http://localhost:8000/api/v1", "sampleUrl": "http://localhost:8000/api/v1", "template": { "withCompare": true, "withGenerator": true } }

3. 添加接口注释

/** * * @api {post get} /{model}/query 查询数据 * @apiName query * @apiGroup 业务单元基础 * @apiVersion 1.0.0 * @apiDescription 接口详细描述 * * @apiParam {Object} body 请求参数JSON对象 * * @apiSuccess {String} status 结果码 * @apiSuccess {String} message 消息说明 * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * code:1, * message:'success', * data:{total:100, result:[]} * } * @apiErrorExample {json} Error-Response: * HTTP/1.1 200 * { * code:0, * message:'user not found', * } * @apiPermission Auth */ query: function (req, res) {}

4. 执行生成命令

apidoc -i ./server/routes/ -o ./doc/apidoc/

---

注意事项

1. @apiGroup 中文问题处理

C:\Users\Administrator\AppData\Roaming\npm\node_modules\apidoc\node_modules\apidoc-core\lib\workers\api_group.js 注释掉 //group = group.replace(/[^\w]/g, ‘_’);

2. @apiName 必须是英文。

接口打开路径会根据 @apiGroup + @apiName