express项目 apidoc 自动生成文档简洁教程

本文是关于apidoc的配置教程，具体的参数请参考官方网站

 

全局安装apidoc

npm i apidoc -g

 

配置api-doc

方式1：根目录添加apidoc.json（推荐），apidoc.json内容如下，具体属性请参考

{ "name": "user-service", "version": "1.0.0", "description": "用户服务API文档", "title": "user-service API Doc", "url": "http://localhost:8080/", "sampleUrl": "http://localhost:8080/", "forceLanguage": "zh-cn", "template": { "withCompare": true, "withGenerator": true } }

方式2：项目package.json配置api-doc

{ "name": "test", "version": "0.0.0", "private": true, "scripts": { "start": "node ./bin/www" }, "dependencies": { "cookie-parser": "~1.4.3", "debug": "~2.6.9", "ejs": "~2.5.7", "express": "~4.16.0", "http-errors": "~1.6.2", "morgan": "~1.9.0" }, "devDependencies": { "express-session": "^1.15.6", "mysql": "^2.15.0" }, "apidoc": { "name": "user-service", "version": "1.0.0", "description": "用户服务API文档", "title": "user-service API Doc", "url": "http://localhost:8080/", "sampleUrl": "http://localhost:8080/", "forceLanguage": "zh-cn", "template": { "withCompare": true, "withGenerator": true } } }

 

编写api文档

以我的项目为例，我的api请求明细写在routes中，那么，我将api文档写在routes的文件中

以查询用户数据的接口为例

var express = require('express'); var router = express.Router(); /** * @apiDefine CODE_200 * @apiSuccess (Reponse 200) {Number} code 0 为成功，-1位异常 * @apiSuccess (Reponse 200) {Json/Array/Null} data 数组或null，需要根据情况判断，一般有值时为数据类型，没有值时为[]或null * @apiSuccess (Reponse 200) {String} msg 请求成功/失败描述信息 * @apiSuccess (Reponse 200) {String} [error_code] 错误码，有时没有 * @apiSuccessExample {json} Response 200 Example * HTTP/1.1 200 OK * { * "code": 0, * "data": [], * "msg": "操作成功" * } */ /** * 通过用户编码查询用户信息 * @api {get} user/getUserInfo 通过用户编码查询用户信息 * @apiName getUserInfo * @apiDescription 通过用户编码查询用户信息 * @apiGroup user * @apiVersion 1.0.0 * @apiParam {String} user_code 用户编码 * @apiParamExample {type} Request-Example: * { * "user_code": "001" * } * @apiSuccessExample {type} Success-Response * HTTP/1.1 200 OK * { * "code": 0, * "data": [ * { * "user_img": "", * "user_name": "", * "user_code": "", * "sex": "", * "national": "", * "idcard": "", * "age": "" * } * ], * "msg": "返回成功" * } * @apiSampleRequest http://localhost:8080/user/getUserInfo * @apiUse CODE_200 */ router.get('/user/getUserInfo', function (req, res, next) { res.json({ code: 0, data: [{ "user_img": "", "user_name": "", "user_code": "", "sex": "", "national": "", "idcard": "", "age": "" }], msg: "返回成功" }); }); module.exports = router;

 

设置静态文件目录

一般这一步在创建项目的时候已经完成，但还是需要检查一下，假设我们需要将文档内容生成再public目录下，我们需要在app.js中配置

// 设置 public 文件夹为存放静态文件的目录 app.use(express.static(path.join(__dirname, 'public')));

 

生成文档

打开终端，cd到项目的根路径下，执行以下命令

apidoc -i routes/ -o public/apidoc/

其中，-i 是api目录； -o 是生成文档的目的地。生成完成后，项目根路径下会生成public/apidoc文件夹。

 

预览

启动项目，在浏览器中输入   http://localhost:3000/apidoc 

其中，3000 是项目启动的端口号，这里是不固定的，视情况而定。打开成功后，会出现这样的内容

至此，文档生成成功。