背景
在前端开发中，避免少不了接口文档，但是手动去写，似乎又太麻烦，于是乎，出现了各种各样的自动化生成的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!
