背景
在前端開發(fā)中嚎货，避免少不了接口文檔橘霎，但是手動(dòng)去寫，似乎又太麻煩殖属，于是乎姐叁，出現(xiàn)了各種各樣的自動(dòng)化生成的API文檔框架，其中比較出名的有Swagger洗显。今天我們不說Swagger外潜，我們說說NodeJs-Express中的apidoc。先看個(gè)Api圖示：
Api文檔配圖
那下面我們就具體看看怎么使用這個(gè)ApiDoc框架吧挠唆！
登錄ApiDoc官網(wǎng)橡卤，熟悉官方文檔 ApiDoc官網(wǎng)
由官網(wǎng)所知，我們使用WebStorm創(chuàng)建好Express項(xiàng)目后损搬，需要安裝一個(gè)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"
}
方式二：項(xiàng)目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的網(wǎng)頁Title
"url": "http://localhost:3000" //Api測(cè)試需要這個(gè)地址，地址必須正確
}
}
編寫api代碼
然后通過在項(xiàng)目的public文件夾下面新建一個(gè)apidoc目錄巧勤。接著嵌灰，我們需要編寫router里的代碼，創(chuàng)建一個(gè)api目錄颅悉，里面編寫一個(gè)User.js接口的東西沽瞭。
文件目錄如下：
項(xiàng)目結(jié)構(gòu)圖
范例：
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;
具體的注解參數(shù)可以查看這個(gè)地址： ApiDoc官網(wǎng)注解說明鏈接
項(xiàng)目terminal執(zhí)行命令行：
apidoc -i routes/ -o public/apidoc/
運(yùn)行
生成成功后，我們就可以測(cè)試運(yùn)行api文檔了剩瓶，訪問路徑：http://localhost:3000/apidoc/index.html
如果運(yùn)行成功驹溃，則就會(huì)看到我們一開始的文檔配圖了。Good Luck!
