如何使用apidocJs快速生成在線文檔

這篇文章將為大家詳細講解有關如何使用apidocJs快速生成在線文檔，小編覺得挺實用的，因此分享給大家做個參考，希望大家閱讀完這篇文章后可以有所收獲。

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

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 參數

一些重要的參數如下表所示：

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": "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塊，這也變成語言的變量功能一直。可以消除重復代碼。

/**
 * @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：不能相加
 */

從下圖中可以看到name和age字段的前面有些縮進，而且字段顯示名為name和age。

關于“如何使用apidocJs快速生成在線文檔”這篇文章就分享到這里了，希望以上內容可以對大家有一定的幫助，使各位可以學到更多知識，如果覺得文章不錯，請把它分享出去讓更多的人看到。