一.apiDoc簡介

apiDoc是用來生成RESTful風格Web API文件的工具，支援現在流行的大部分程式語言，如Python,Java,C#, Go, Dart, Java, JavaScript, PHP, Scala 等。在原始碼的註釋中使用apiDoc提供的註解資訊來生成文件資訊。

在我們日常開發中一定會寫開發文件，以前常見的做法是維護一個或多個markdown檔案，每次api改動時都要去對應檔案位置進行修改。這種方式維護起來相當麻煩，而且相對於網頁來說markdown只能提供簡單的閱覽功能不能實時檢視介面呼叫結果，對開發者來說api也不友好。所以找一個更好的文件處理方式已經是迫在眉睫，現在apiDoc可以讓你可以解脫了。
apiDoc的gitHub地址：

二.Ubuntu安裝apiDoc

按照官方文件安裝apiDoc會出現一些問題。主要原因是因為apiDoc需要依賴nodejs，所以需要先安裝nodejs然後安裝apiDoc就可以了。

2.1 安裝nodejs

更新ubuntu軟體源

sudo apt-get update
sudo apt-get install -y python-software-properties software-properties-common
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update

安裝nodejs

sudo apt-get install nodejs
sudo apt install nodejs-legacy
sudo apt install npm

更新npm的包映象源

sudo npm config set registry https://registry.npm.taobao.org
sudo npm config list

全域性安裝n管理器(用於管理nodejs版本)

sudo npm install n -g

安裝最新的nodejs（stable版本）

sudo n stable
sudo node -v

2.2安裝apiDoc

上面的操作順利完成後再執行下面命令就OK了。

sudo npm install apidoc -g

三.apiDoc入門

3.1 執行官方Demo

首先下載官方github上的原始碼。
然後進入

apidoc/example/

最後執行

apidoc -i example/ -o doc/

這個命令就能滿足基本需求了，詳細的命令引數檢視官方文件。生成的文件在指定的檔案doc中，開啟index.html。官方線上例子

3.2 配置檔案介紹

如Demo中的檔案結構
.
├── _apidoc.js 需要生成api文件的原始碼檔案
├── apidoc.json 配置檔案
├── example.js 需要生成api文件的原始碼檔案
├── footer.md 生成api文件的自定義頭部資訊，支援markdown標籤。
└── header.md 生成api文件的自定義底部資訊，支援markdown標籤。

apidoc.json檔案相當簡單對比Demo生成的文件可以輕鬆理解。

{
  "name": "apidoc-example-test",
  "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
  }
}

3.3 常用註解介紹

具體文件可參考：http://apidocjs.com/

/**
 * @api {get} /user/:id Read data of a User
 * @apiVersion 0.3.0
 * @apiName GetUser
 * @apiGroup User
 * @apiPermission admin
 *
 * @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
 *
 * @apiParam {Number} id The Users-ID.
 *
 * @apiExample Example usage:
 * curl -i http://localhost/user/4711
 *
 * @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.
 *
 * @apiError NoAccessRight Only authenticated Admins can access the data.
 * @apiError UserNotFound   The <code>id</code> of the User was not found.
 *
 * @apiErrorExample Response (example):
 *     HTTP/1.1 401 Not Authenticated
 *     {
 *       "error": "NoAccessRight"
 *     }
 */
function getUser() { return; }

重點介紹下@apiParam：
語法：

@apiParam [(group)] [{type}] [field=defaultValue] [description]

描述如何將引數傳遞給你的api方法。文件描述
例如: @apiParam (MyGroup) {Number} id Users unique ID.
注意：該標籤適用於三種引數形式
a.動態路由：http://localhost/sutdent/:id
b.請求引數：http://localhost/sutdent?id=:id
c.表單引數：http://localhost/sutdent
在生成文件中id引數可以在“Send a Sample Request”傳送時被替換成具體的值方便檢視api的返回結果。

一個問題

這裡丟擲一個問題：apidoc是比較“底層”的文件生成方式，能否不手動寫apiDoc的標籤而是直接根據後端程式碼基於apiDoc來直接生成api文件？
答案當然是肯定有的了，有興趣的可以自己找找看或自己寫寫看，如果寫好了可以告訴我哦。

參考連結：http://www.jianshu.com/p/2b24cd430a7d