利用apidoc維護api接口文檔

什麼是apidoc

apidoc是一個輕量級的在線REST接口文檔生成系統，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者按照要求書寫相關注釋，就能夠生成可讀性好、界面美觀的在線接口文檔。

這裏瞭解更多

快速開始

• 安裝依賴

  • 安裝nodejs https://nodejs.org/官網下載.msi文件；
    測試是否安裝成功 npm -v
  • npm的安裝。因爲新版的NodeJS已經集成了npm，因此以前npm也一併安裝好了。一樣能夠使用cmd命令行輸入"npm -v"來測試是否成功安裝。以下圖，出現版本提示便OK了。

• 安裝apidoc

  利用npm進行安裝

  npm install apidoc -g

安裝速度和網速有關，最多1到2分鐘，

apidoc -v  能夠查看版本信息

安裝好後在

C:\Users\admin\AppData\Roaming\npm\node_modules\apidoc

可以看到以下文件

• apidoc配置

  打開example文件夾apidoc.json爲配置文件,修改參數爲本身的項目信息。

{
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apidoc example project",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1",
  "sampleUrl": "https://api.github.com/v1",
  "header": {
    "title": "My own header title",
    "filename": "header.md"
  },
  "footer": {
    "title": "My own footer title",
    "filename": "footer.md"
  },
  "template": {
      "withCompare": true,
      "withGenerator": true
  }
}

將 apidoc.json 拷貝到須要生成文檔的目錄下

而後按照文檔說明作代碼註釋

/**
 * @api {get} /sguoshan_api/Logon 獲取用戶信息
 * @apiVersion 1.0.0
 * @apiName  Logon
 * @apiGroup User
 * @apiPermission 全部已註冊用戶
 * @apiPrivate
 * @apiDescription 與0.9.0相比安全性提升
 *
 * @apiParam {String} username 用戶名稱/郵箱/會員號
 * @apiParam {Number} password 用戶密碼
 * @apiExample 使用示例:
 * http://api.guoshanchina.com/sguoshan_api/Logon?username=911117&password=123456
 *
 * @apiSuccess {Number}   id            The Users-ID.
 * @apiSuccess {Date}     registered    Registration Date.
 * @apiSuccess {Date}     name          Fullname of the User.
 * @apiSuccess {String[]} nicknames     List of Users nicknames (Array of Strings).
 * @apiSuccess {Object}   profile       Profile data (example for an Object)
 * @apiSuccess {Number}   profile.age   Users age.
 * @apiSuccess {String}   profile.image Avatar-Image.
 * @apiSuccess {Object[]} options       List of Users options (Array of Objects).
 * @apiSuccess {String}   options.name  Option Name.
 * @apiSuccess {String}   options.value Option Value.
 *
 * @apiSuccessExample 成功 return ():
{
"msg": "獲取成功",
"status":"200",
"data":{
    "id":"123",
    "name":"shmily"
    }
}
 * @apiError NoAccessRight     只用登錄成功才能訪問.
 * @apiError UserNotFound   用戶 <code>id</code> 錯誤.
 * @apiErrorExample 失敗 return ():
 *     HTTP/1.1 401 Not Authenticated
 *     {
 *       "msg": "沒有權限","status":"401"
 *     }
 */
function getUser() { return; }

在命令行中

切換到項目apidoc.json的上一級（api目錄）
d:
cd www/shop/Web
apidoc -i api/ -o apidoc/

運行後在api的同級目錄可以看到生成了apidoc的文件夾。雙擊文件夾下的index.html，就能看到文檔了。