官方文檔連接：http://apidocjs.com/#demo
apidoc是一個輕量級的在線REST接口文檔生成系統，支持多種主流語言，包括Java、C、C#、PHP和Javascript等。使用者僅需要按照要求書寫相關注釋，就可以生成可讀性好、界面美觀的在線接口文檔。本文主要包含以下內容：
- 介紹apidoc的基本概念
- 安裝、使用和簡單配置
- 一些特殊參數的含義及其使用
- 介紹一些使用經驗
前言
apidoc能做什么
apidoc是一個輕量級的在線REST接口文檔生成系統，可以根據其特定的規則的代碼注釋來生成靜態網頁。首先看下它生成的文檔界面和風格。
支持
apidoc支持多種主流的編碼語言，包括Java、C、C#、PHP和Javascript。一般情況下，語言會有多種注釋方法，例如就Java中有普通風格的多行注釋和Javadoc風格的注釋。apidoc並不支持所有的注釋，譬如Java僅中支持Javadoc風格的注釋。首先要說明的是，apidoc並不具備語義識別能力，它不會發現代碼中是否有BUG，它僅僅通過文件后綴來判斷語言類型。下面是一些不同語言注釋示例：
* Java、Javascript、PHP *
/** * @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. */
* Python *
""" @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. """
安裝
apidoc是基於nodeJs平台，在安裝apidoc之前，需要先安裝nodeJs。關於nodeJs的安裝，一搜一大把，不過為了文章的完整性，還是首先介紹一下Windows平台下nodeJs的安裝。
nodeJs安裝
首先，去node.js官網上下載最新的安裝包，請下載自己對應系統的安裝包。譬如筆者的操作系統是64位Windows操作系統，就下載下圖所示的node安裝包。
下載完畢后，按照一般的軟件安裝步驟安裝即可。由於筆者的計算機已經安裝過了，在這里就不過細演示了。
按理來說，按照安裝步驟安裝完畢后，node環境也已經配置好了，現在來驗證一下node是否已正確安裝配置。
首先，打開Window Shell窗口。使用win+R快捷鍵打開運行窗口，在文本框中輸入cmd並回車打開Windows Shell。
然后，在控制台輸入node命令進入node控制台。
最后，運行一個Hello World程序。在node控制台中輸入console.info("hello world");，如果輸出如下圖所示的結果，則表示node安裝配置成功。
除了node之外，npm（node package manager，node安裝包管理器）也是很重要的，可以通過它來便捷地下載和安裝node應用。在Windows Shell中輸入npm命令，如果出現如下圖所示的信息，則表示npm也正確安裝完畢。
apidoc安裝
apidoc可以利用npm來快速安裝。
1、進入Windows Shell，輸入npm install apidoc -g進行apidoc的安裝，如下圖。
等待一定時間（根據自身的網速）的下載和安裝之后，如果出現下圖所示的信息，則表示apidoc安裝成功。
2、在Windows Shell中輸入apidoc -v命令，如果出現如下圖所示的界面，則表示apidoc已安裝成功。
初步使用
下面通過一些簡單的demo來介紹如何利用apidoc生成一份在線接口文檔。
命令行
在正式開始之前，先介紹一下apidoc中的重要命令和參數。apidoc的命令格式如下：
apidoc 參數
一些重要的參數如下表所示：
參數 描述 -f 選擇要解析的文件，支持正則表達式。-f參數可以使用多次，多個表達式可以對應不同的-f。如：apidoc -f ".*\.js$" -f ".*\\.ts$" -i 選擇源代碼所在的位置。如：apidoc -i myapp/ -o 選擇生成的目標文件所在的位置。如：apidoc -o apidoc/ -t 為生成文件選擇模板，可以創建和使用自定義的模板。（筆者注：目前為止，筆者還沒有使用過這個參數） -h 跟絕大多數命令一樣，這個參數可以打印出幫助文檔
apidoc -i src/ -o apidoc/ # 可以通過搜索src目錄中的文件快速的生成文檔文件，並將這些文件放在apidoc目錄下。
apidoc -h # 顯示幫助信息
使用apidoc
一個典型的文件目錄結果如下圖所示。
其中：
- apidoc.json：apidoc的項目級配置文件，它必須位於整個工程目錄頂層。
- Demo1.java：用於演示的demo源文件，它可以位於整個工程目錄的頂層目錄及其子目錄下。apidoc會搜索整個工程目錄選擇所有可能的源文件。
apidoc.json和Demo1.java中包含的代碼分別如下：
{ "name": "demo", "version": "1.0.0", "description": "這是一個簡單的apidoc的demo", "title": "demo", "url" : "https://api.github.com/v1" }
/** * @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. */
下面通過這個demo來介紹如何生成文檔文件。
首先，在Windows Shell中進入apidoc工程目錄的上層目錄。例如筆者的apidoc的工程位於E:\workspaces\sublime\apidoc路徑下。在這個目錄中創建名為src的工程目錄，將apidoc.json和Demo1.java文件置於src目錄下。
然后，在Windows Shell中輸入apidoc -i src/ -o apidoc/命令，如果出現如下圖所示的Done結果，則表明文檔已經生成，位於同級目錄的apidoc（與-o apidoc對應）目錄下。
最后，打開apidoc目錄，可以看到如下圖所示的靜態Web文件。雙擊index.html就可以在瀏覽器中打開生成在線接口文檔網站
這樣我們就成功地生成了一份在線接口文檔了，接下來就只要部署到任意Web容器（Apache、Tomcat等）就可以將接口文檔對外發布了，So easy！
配置
apidoc.json文件是項目級的配置文件，接下來簡單地介紹一下其中常用的配置項。
配置名 描述
name 工程名。如果該字段不存在，則apidoc會嘗試通過package.json（apidoc頂層配置文件）來生成
version 工程文檔的版本號。如果該字段不存在，則apidoc會嘗試通過package.json（apidoc頂層配置文件）來生成
description 工程詳細描述。如果該字段不存在，則apidoc會嘗試通過package.json（apidoc頂層配置文件）來生成
title 文檔標題，顯示在文檔界面的最上方
url 整個api url的前綴，接下來的所有接口url都會加上這個前綴
sampleUrl api示例的url前綴。如果設置了這個值，則界面中顯示請求表單，可以用於測試接口
header
title 文檔頭（header）的連接錨點名
filename 文檔頭所使用的文件
footer
title 文檔尾（footer）的連接錨點名
filename 文檔尾所使用的文件
order 接口的排列順序list，如果不指定，則由apidoc自行確定
一個比較完整的配置文件如下：
{ "name": "demo", "version": "1.0.0", "description": "這是一個簡單的apidoc的demo", "title": "demo", "url": "https://api.github.com/v1", "sampleUrl": "https://api.github.com/v1/test", "header": { "title": "header", "filename": "header.md" }, "footer": { "title": "footer", "filename": "footer.md" }, "order": [ "Error", "Define", "PostTitleAndError", "PostError" ] }
更多的配置項請參考apidoc官方文檔站點。
Params
apidoc中最核心的東西就是參數（params）的書寫，本節介紹apidoc中一些重要的params。
@api
@api定義一個特定的接口。如果一個注釋塊既不包含@apiDefine又沒有包含@api參數，則apidoc會直接忽略這個注釋塊。這個參數在界面上表示一個接口區域塊如下:
@api的書寫格式為：
@api {method} path [title]
注意，[xxx]表示一個可選的參數，下同。
下表介紹了@api中的參數含義。
更多的配置項請參考apidoc官方文檔站點。
@apiDefine
@apiDefine表示定義一個變量，該變量可以指代任意值（字符串、參數塊），這個參數並且寫在獨立的代碼塊中。可以使用@apiUse來使用其定義的變量。
@apiDefine的書寫格式為：
@apiDefine name [title] [description]
下面的代碼定義一個錯誤塊，然后在接口定義中引用使用這個錯誤塊。多個不同接口可以引用同樣的@apiDefine塊，這也變成語言的變量功能一直。可以消除重復代碼。
/** * @apiDefine MyError * @apiError UserNotFound The <code>id</code> of the User was not found. */ /** * @api {get} /user/:id * @apiUse MyError */
@apiDescription
用於@api代碼塊中，用於詳盡地描述接口的功能。
@apiDescription的書寫格式為：
@apiDescription text
text就是具體的描述內容，可以直接使用Markdown語法，這極大地豐富了其表現形式。
@apiGroup
表示接口所屬的組，最直接的體現就是在側邊導航中將接口分在對用的組中。
@apiGroup的書寫格式為：
@apiGroup name
name表示組名，可以是任意字符串。值得注意的是，name不支持中文，一旦輸入中文，apidoc就會忽略這些中文字符。如果需要在界面中顯示中文接口組名，只需要使用@apiDefine定義一個中文字符串，然后name用變量名替換即可。
/** * @apiDefine group 測試 */ /** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup group */
@apiName
表示接口的名字，應該在每個@api塊中使用。可以生成一個Web錨點，快速定位接口位置。可以看到錨點（url的#后面的字符串）通常由groupName-apiName構成。
@apiName的書寫格式為：
@apiName name
@apiUse
表示引用一個@apiDefine定義的值或塊，相當於直接替換變量的值。
@apiUse的書寫格式為：
@apiUse name
name是一個已定義的@apiDefine中的name，如果輸入的name不存在，則會拋出類似下面的異常信息。
{ File: 'src\\Demo1.java',
Block: 4,
Element: '@apiUse',
Groupname: 'test',
Definition: '@apiUse group',
Example: '@apiDefine MyValidGroup Some title\n@apiUse MyValidGroup' }
下面是一個示例：
/** * @apiDefine test * @apiParam {Number} id Users unique ID. */ /** * @apiUse test * @apiParam {Number} name name. */
@apiParam
表示一個請求參數。
@apiParam的書寫格式為：
@apiParam [(group)] [{type}] [field=defaultValue] [description]
下表介紹了@apiParam中的參數含義。
下面是一個簡單的示例：
/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. */ /** * @api {post} /user/ * @apiParam {String} [firstname] 用戶名（非必填）. * @apiParam {String} lastname 用戶姓（必填）. */
@apiSuccess
表示請求成功時的一個返回字段。
@apiSuccess的書寫格式為：
@apiSuccess [(group)] [{type}] field [description]
@apiSuccess的參數含義與@apiParam一致，這里就不再做說明了。
@apiError
表示請求失敗時的一個返回字段。
@apiError的書寫格式為：
@apiError [(group)] [{type}] field [description]
與apiSuccess的參數含義完全一致。
@apiParamExample
表示一個請求范例。
@apiParamExample的書寫格式為：
@apiParamExample [{type}] [title] example
下面是一個簡單的示例：
/** * @api {get} /user/:id * @apiParamExample {json} Request-Example: * { * "id": 4711 * } */
@apiSuccessExample
表示一個響應范例。其書寫格式和參數含義與@apiParamExample完全一樣。
@apiSampleRequest
表示一個接口測試塊，可以根據定義的請求參數來生成一個表單，用來進行接口測試。
@apiSampleRequest的書寫格式為：
@apiSampleRequest url
url可以與配置文件（apidoc.json）中的sampleUrl以及@api定義的path連接成一個完整的測試url。例如：
/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. * @apiSampleRequest /test */
一些實際經驗
下面介紹一下在實際使用過程發現的東西。
絕大部分地方可使用Markdown語法
在幾乎所有的描述類字段處都可以使用符合Markdown語法的文本，可以使得文檔形式更加美觀。
/** * @api {get} /user/:id * @apiParam {String} rule * * - 規則1：不能使用小數 * - 規則2：不能相加 */
對象類型的參數
如果請求的參數是一個對象，那此時因為如果書寫呢？比如需要Post一個Person對象，Person中包括name、age字段，那么可以這樣書寫。
/** * @api {post} /user * @apiName obj * @apiParam {Object} person * @apiParam {String} person.name 姓名 * @apiParam {Integer} person.age 年齡 */
從下圖中可以看到name和age字段的前面有些縮進，而且字段顯示名為name和age。
本文由xialei原創，轉載請說明出處http://hinylover.space/2016/03/31/create-online-document-use-apidoc/。