使用apidocJs快速生成在線文檔

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

1. 介紹apidoc的基本概念
2. 安裝、使用和簡單配置
3. 一些特殊參數的含義及其使用
4. 介紹一些使用經驗

前言

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

一個典型的文件目錄結果如下圖所示。

其中：

1. apidoc.json：apidoc的項目級配置文件，它必須位於整個工程目錄頂層。
2. 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中的參數含義。

參數	描述
method	請求的HTTP方法名，包括DELETE, GET, POST, PUT，更多方法詳見http-learn-url
path	請求的url path（不包括前綴）
title	接口名，用於接口索引。這個配置項會顯示在導航菜單中。

更多的配置項請參考apidoc官方文檔站點。

@apiDefine

@apiDefine表示定義一個變量，該變量可以指代任意值（字符串、參數塊），這個參數並且寫在獨立的代碼塊中。可以使用@apiUse來使用其定義的變量。

@apiDefine的書寫格式為：

@apiDefine name [title] [description]

下表介紹了@apiDefine中的參數含義。

參數	描述
name	值或者塊的名字，可以看做就是變量名
title	標題，一般用於@apiParam (name)參數，顯示請求參數所在組的名稱
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中的參數含義。

參數	描述
(group)	參數所在的組，可以使用@apiDefine定義的值
{type}	參數的類型。例如 {Boolean}, {Number}, {String}, {Object}, {String[]} (array of strings), ..
field	請求參數名。
[field]	表示這個參數是個可選參數，非必傳參數。
=defaultValue	表示這個參數的默認值。
description	這個請求參數的描述，支持Markdown語法。

下面是一個簡單的示例：

/**
 * @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

 

參數	描述
{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。

 

本想自己寫這么一篇文章，發現有個博主寫的很不錯，就直接轉載過來：

http://blog.csdn.net/xialei199023/article/details/63251482

apidoc 官網：http://apidocjs.com/