NodeJs - Express项目 自动生成API文档

背景

在前端开发中，避免少不了接口文档，但是手动去写，似乎又太麻烦，于是乎，出现了各种各样的自动化生成的API文档框架，其中比较出名的有Swagger。今天我们不说Swagger，我们说说NodeJs-Express中的apidoc。先看个Api图示：

Api文档配图

那下面我们就具体看看怎么使用这个ApiDoc框架吧！

登录ApiDoc官网，熟悉官方文档 ApiDoc官网

由官网所知，我们使用WebStorm创建好Express项目后，需要安装一个ApiDoc库，代码如下：

npm i apidoc -g   #全局安装

接着配置api-doc

方式一：根目录配置apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

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

{
  "name": "helo",
  "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": {  //配置api-doc
    "title": "接口文档", //Api-Doc的网页Title
    "url": "http://localhost:3000" //Api测试需要这个地址，地址必须正确
  }
}

编写api代码

然后通过在项目的public文件夹下面新建一个apidoc目录。接着，我们需要编写router里的代码，创建一个api目录，里面编写一个User.js接口的东西。

文件目录如下：

项目结构图

范例：

let express = require('express');
let router = express.Router();

/**
 * @api {post} /api/user/submit-login 用户登录
 * @apiDescription 用户登录
 * @apiName submit-login
 * @apiGroup User
 * @apiParam {string} loginName 用户名
 * @apiParam {string} loginPass 密码
 * @apiSuccess {json} result
 * @apiSuccessExample {json} Success-Response:
 *  {
 *      "success" : "true",
 *      "result" : {
 *          "name" : "loginName",
 *          "password" : "loginPass"
 *      }
 *  }
 * @apiSampleRequest http://localhost:3000/api/user/submit-login
 * @apiVersion 1.0.0
 */
router.post('/submit-login', function (req, res, next) {
    let loginName = req.body.loginName;
    let loginPass = req.body.loginPass;
    res.json({
        success: true,
        result: {
            name: loginName,
            password: loginPass
        }
    });
});

module.exports = router;

具体的注解参数可以查看这个地址： ApiDoc官网注解说明链接

项目terminal执行命令行：

apidoc -i routes/ -o public/apidoc/

运行

生成成功后，我们就可以测试运行api文档了，访问路径：http://localhost:3000/apidoc/index.html

如果运行成功，则就会看到我们一开始的文档配图了。Good Luck!