原文地址：樑桂釗的部落格
在服務端開發過程中，我們需要提供一份 API 介面文件給 Web 端和移動端使用。實現 API 介面文件編寫工作，有很多種方式，例如通過 Word 文件編寫，或者通過 MediaWiki 進行維護。此外，還有比較流行的方式是利用 Swagger 自動化生成文件。這裡，筆者想分享另一個 Web API 文件生成工具 apidoc。
apidoc 是通過原始碼中的註釋來生成 Web API 文件。因此，apidoc 對現有程式碼可以做到無侵入性。此外，apidoc 可以支援多種語言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby，Lua。通過 apidoc 可以非常方便地生成可互動地文件頁面。
開始入門
首先，我們需要 node.js 的支援。在搭建好 node.js 環境後，通過終端輸入 npm 命名進行安裝。
npm install apidoc -g
複製程式碼接著，我們還需要新增 apidoc.json 檔案到專案工程的根目錄下。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
複製程式碼這裡，筆者主要演示 Java 註釋如何和 apidoc 結合使用。現在，我們先來看一個案例。
/**
* @api {GET} logistics/policys 查詢簽收預警策略
* @apiDescription 查詢簽收預警策略
* @apiGroup QUERY
* @apiName logistics/policys
* @apiParam {Integer} edition 平臺型別
* @apiParam {String} tenantCode 商家名稱
* @apiPermission LOGISTICS_POCILY
*/
複製程式碼最後，我們在終端輸入 apidoc 命令進行文件生成。這裡，我們用自己的專案工程的根目錄替代 myapp/,用需要生成文件的地址替代 apidoc/。
apidoc -i myapp/ -o apidoc/
複製程式碼例如，筆者的配置是這樣的。
apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/
複製程式碼程式碼註釋
@api
@api 標籤是必填的，只有使用 @api 標籤的註釋塊才會被解析生成文件內容。格式如下：
@api {method} path [title]
複製程式碼這裡，有必要對引數內容進行講解。
| 引數名 | 描述 |
|---|---|
| method | 請求方法, 如 POST，GET，POST，PUT，DELETE 等。 |
| path | 請求路徑。 |
| title【選填】 | 簡單的描述 |
@apiDescription
@apiDescription 對 API 介面進行描述。格式如下：
@apiDescription text
複製程式碼@apiGroup
@apiGroup 表示分組名稱，它會被解析成一級導航欄選單。格式如下：
@apiGroup name
複製程式碼@apiName
@apiName 表示介面名稱。注意的是，在同一個 @apiGroup 下，名稱相同的 @api 通過 @apiVersion 區分，否者後面 @api 會覆蓋前面定義的 @api。格式如下：
@apiName name
複製程式碼@apiVersion
@apiVersion 表示介面的版本，和 @apiName 一起使用。格式如下：
@apiVersion version
複製程式碼@apiParam
@apiParam 定義 API 介面需要的請求引數。格式如下：
@apiParam [(group)] [{type}] [field=defaultValue] [description]
複製程式碼這裡，有必要對引數內容進行講解。
| 引數名 | 描述 |
|---|---|
| (group)【選填】 | 引數進行分組 |
| {type}【選填】 | 引數型別，包括{Boolean}, {Number}, {String}, {Object}, {String[]}， (array of strings), ... |
| {type{size}}【選填】 | 可以宣告引數範圍，例如{string{..5}}， {string{2..5}}， {number{100-999}} |
| {type=allowedValues}【選填】 | 可以宣告引數允許的列舉值，例如{string="small","huge"}， {number=1,2,3,99} |
| field | 引數名稱 |
| [field] | 宣告該引數可選 |
| =defaultValue【選填】 | 宣告該引數預設值 |
| description【選填】 | 宣告該引數描述 |
類似的用法，還有 @apiHeader 定義 API 介面需要的請求頭，@apiSuccess 定義 API 介面需要的響應成功，@apiError 定義了 API 介面需要的響應錯誤。
這裡，我們看一個案例。
/**
* @apiParam {Integer} edition=1 平臺型別
* @apiParam {String} [tenantCode] 商家名稱
*/
複製程式碼此外，還有 @apiParamExample，@apiHeaderExample， @apiErrorExample，@apiSuccessExample 可以用來在文件中提供相關示例。
@apiPermission
@apiPermission 定義 API 介面需要的許可權點。格式如下：
@apiPermission name
複製程式碼此外，還有一些特別的註解。例如 @apiDeprecated 表示這個 API 介面已經廢棄，@apiIgnore 表示忽略這個介面的解析。關於更多的使用細節，可以閱讀官方文件：http://apidocjs.com/#demo
完整的案例
最後，我們用官方的案例，講解下一個完整的配置。
首先，配置 apidoc.json，內容如下：
{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}
複製程式碼接著，我們配置相關的 Java 原始碼註釋。
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
複製程式碼然後，執行命名生成文件。
apidoc -i myapp/ -o apidoc/
複製程式碼生成的頁面，如下所示。
（完）
更多精彩文章，盡在「服務端思維」微信公眾號！
