Node與apidoc的邂逅——NodeJS Restful 的API文檔生成

　　作為后台根據需求文檔開發完成接口后，交付給前台（angular vue等）做開發，不可能讓前台每個接口調用都去查看你的后台代碼一點點查找。前台開發若不懂你的代碼呢？讓他一個接口一個接口去問你怎么調用，需要傳遞那些參數？調用方法？這樣的話，微信公眾號之類的二次開發去找誰要接口調用，這顯然是不切合實際的。所以有一個后台接口調用的展示文檔，對前后端分離的開發來說，非常實用。之前在.net 開發中使用過swagger作為后台接口API文檔的生成方式。感覺很簡單，一步到位。下面介紹一下在nodejs 中采用apidoc來生成Restful API 的接口文檔。

　　1.首先APIDOC的官網，關於配置等內容可以參看說明

　　http://apidocjs.com

　　2.具體操作說明:

　　1)安裝node環境（這個不多說），安裝apidoc

npm install apidoc -g

　　2)打開你的項目，在根目錄創建一個配置文件apidoc.json，里邊的內容可參考我的配置:

{
  "name": "cms-server", // 你的項目名稱，可以隨便寫
  "version": "1.0.0", // 版本,書寫沒要求
  "description": "cms-server項目API文檔", // API文檔的描述
  "title": "cms-server API",  // API文檔的標題
  "url" : "http://localhost:3001/v1", // 項目接口的地址，如我的user接口：localhost:3001/v1/user
  "sampleUrl": "http://localhost:3001/v1",
  "forceLanguage":"zh-cn",
  "template": {
    "withCompare": true,
    "withGenerator": true
  }

}

　　3)新建一個文件夾，用於存放你的APIDOC生成的文件，然后在項目的啟動文件，如app.js添加下邊一句話

app.use('/apidoc存放的位置',express.static('apidoc存放的位置'));
// 配置實例：若我放在public/apidoc,則對應配置為
app.use('/public',express.static('public'));
// 那么我訪問的地址應該是:
// localhost:3001/public/apidoc,他就會自動運行apidoc下生成的apidoc/index.html

　　4)在對應的接口上添加注釋，可參考下邊的配置　

/**
 * 獲得某個用戶
 * @api {GET} /api/users/:id 獲得某個用戶
 * @apiDescription 根據ID獲得某個用戶
 * @apiName getUser
 * @apiParam (path參數) {Number} id
 * @apiSampleRequest /api/users/5a45cefd080d7c39a036ca55
 * @apiGroup User
 * @apiVersion 1.0.0
 */

　　5) 生成API文檔

//apidoc -i '掃描接口的文件夾' -o '生成apidoc的位置'
//如:
apidoc -i app/api -o public/apidoc

　　6)啟動項目，訪問http:localhost:3001/public/apidoc，就可以看到生成的api文檔。

參考生成的api文檔：