apidoc 後端接口註釋文檔簡單使用

apidoc使用指南

一、安裝

# 全局安裝
npm install apidoc -g   
# 查看是否安裝成功,顯示命令行參數
apidoc -h 

二、具體使用

    # 1.在項目文件夾新建apidoc.json;
    # 2.在項目根目錄運行
    # apidoc -i 源目錄 -o  目標目錄
    apidoc -i ./router -o ./publish
    # 簡寫指令
    apidoc

說明：上面的指令可以直接簡寫爲 apidoc，沒有任何參數時，默認從當前目錄(包括子目錄)下格式爲(.cs .dart .erl .go .java .js .php .py .rb .ts) 的所有文件生成文檔並將輸出寫入 ./doc/。

三、基本配置

項目根目錄下的 apidoc.json 可配置項包含有關項目的常用信息，如 標題，簡短描述、版本和配置選項，如頁眉/頁腳設置或模板特定選項。

1.基本配置方式（apidoc.json）

{
    "name": "user",
    "version": "1.0.0",
    "description": "用戶操作接口文檔",
    "title": "user",
    "url": "http://127.0.0.1:3000"
}

2.在含有package.json文件的項目中配置(添加"apidoc":{}參數)

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

四、使用

在相關接口上插入註釋，例：

/**
 * @api {get} /getuser 用戶需求
 * @apiVersion 1.0.0
 * @apiGroup getUser
 *
 * @apiParam {String} id 用戶id
 * @apiParam {String} uname 用戶名-非空
 * @apiParam  {String} uage 年齡

 * @apiSuccess {Object} status 狀態
 * @apiSuccess {Object} msg  提示信息
 * @apiSuccess {String[]} data  返回數據
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *          "status":0,
 *          "reason":"查詢成功",
 *          "data":[]
 *      }
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
router.get('/getuser', (req, res, next) => {
    var sql = 'update user set ? where id=?';
    var body = {
        id: req.query.id,
        uname: req.query.uname,
        uage: req.query.uage
    }
    conn.query(sql, [body, body.id], (err, result) => {
        if (err) console.log(result);
        console.log(result);
    })
})

再使用命令

    apidoc -i ./router -o ./publish

即可生成接口文檔，打開./publish/apidoc/index.html即可查看接口文檔

效果如下：

參考：
https://www.jianshu.com/p/0a3...
http://apidocjs.com/