Apidoc使用說明

Apidoc 使用說明

使用apidocJs快速生成線上文檔

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 *

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的安裝

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安裝配置成功。

apidoc安裝

apidoc可以利用npm來快速安裝。

1、進入Windows Shell，輸入npm install apidoc -g進行apidoc的安裝，如下圖。

等待一定時間（根據自身的網速）的下載下傳和安裝之後，如果出現下圖所示的資訊，則表示apidoc安裝成功。

2、在Windows Shell中輸入apidoc -v指令，如果出現如下圖所示的界面，則表示apidoc已安裝成功。

三、apidoc的使用

下面通過一些簡單的demo來介紹如何利用apidoc生成一份線上接口文檔。

指令行

在正式開始之前，先介紹一下apidoc中的重要指令和參數。apidoc的指令格式如下：

apidoc 參數

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

參數 描述

-f 選擇要解析的檔案，支援正規表達式。-f參數可以使用多次，多個表達式可以對應不同的-f。如：apidoc -f “.*.js " − f " . ∗ . t s " -f ".*\\.ts "−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”: “PFT API Document”,

“version”: “0.1.0”,

“description”: “PFT API document generated from apiDoc”,

“title”: “PFT API”,

“url” : “http://localhost:9000”,

“sampleUrl”: “http://localhost:9000”,

“header”: {

“title”: “Overview”,

“filename”: “header.md”

},

“footer”: {

“title”: “Copyright”,

“filename”: “footer.md”

},

“template”: {

“withCompare”: true,

“withGenerator”: true

}

}

下面通過這個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！

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

@apiDescription

用于@api代碼塊中，用于詳盡地描述接口的功能。

@apiDescription的書寫格式為：

@apiDescription text

text就是具體的描述内容，可以直接使用Markdown文法，這極大地豐富了其表現形式。

@apiGroup

表示接口所屬的組，最直接的展現就是在側邊導航中将接口分在對用的組中。

@apiGroup的書寫格式為：

@apiGroup name

name表示組名，可以是任意字元串。值得注意的是，name不支援中文，一旦輸入中文，apidoc就會忽略這些中文字元。如果需要在界面中顯示中文接口組名，隻需要使用@apiDefine定義一個中文字元串，然後name用變量名替換即可。

@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\[email protected] MyValidGroup’ }

下面是一個示例：

@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文法。

下面是一個簡單的示例：

@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。例如：

生成的界面截圖如下：

一些實際經驗

下面介紹一下在實際使用過程發現的東西。

絕大部分地方可使用Markdown文法

在幾乎所有的描述類字段處都可以使用符合Markdown文法的文本，可以使得文檔形式更加美觀。

對象類型的參數

如果請求的參數是一個對象，那此時因為如果書寫呢？比如需要Post一個Person對象，Person中包括name、age字段，那麼可以這樣書寫。

四、自動化導出Markdown接口文檔

面對如此強大的apidoc工具，我一度以為可以通過修改輸出模闆檔案來導出markdown檔案，但通過檢視目前版本(0.17.6)源代碼，我發現apidoc在生成輸出檔案的時候僅僅是将模闆檔案拷貝到輸出目錄下，并沒有像我想象的那樣根據模闆檔案生成輸出文檔，apidoc所做的工作主要是通過讀取源代碼中的注釋，解析生成一個api_data.json檔案，這個檔案裡面包含了所有從注釋中提取粗來的接口資料。是以接下來的工作便是根據這個api_data.json檔案生成markdown檔案即可。

幸運的是，GitHub上已經有好心人為我們做了這個工作。

4.1 安裝apidoc-markdown

apidoc-markdown是一個根據apidoc輸出檔案直接生成markdown檔案的工具。首先我們需要安裝該工具：

npm install apidoc-markdown -g

4.2 導出Markdown文檔

apidoc-markdown主要指令參數如下：

參數 描述

-p, --path 指定apidoc生成的文檔目錄

-o, --output 指定輸出的markdown檔案路徑(包含檔案名)例如:apidoc-markdown -o output_dir/markdown_name.md

-t, --template 指定生成markdown檔案的模闆檔案(EJS模闆檔案)預設:使用工具自帶的模闆檔案

通常情況下，我們需要允許下面這樣的指令:

apidoc-markdown -p apidoc_dir -o doc/doc_markdown.md

這樣我們便完成了接口文檔從HTML到Markdown檔案的轉化。

4.3 添加自定義的markdown模闆檔案

由于該工具自帶的markdown模闆并不是非常完美，對于api_data.json檔案中的字段并不是完全解析，是以你需要自己分析api_data.json中的資料接口，完善markdown模闆檔案。該檔案是EJS模闆檔案，文法比較簡單，有需要的童鞋可以自行Google，另外您也可以下載下傳該工具的源代碼，修改裡面自帶的模闆檔案也比較友善。

五、自動化導出PDF接口文檔

既然markdown檔案都有了，那麼導出PDF檔案不是更簡單了。在這裡，寡人推薦一個灰常好用的markdown離線編輯工具——Typora

Typora是一款離線輕量Markdown編輯器，該工具非常簡潔、易用(目前處于測試階段，可免費使用)。具體如何簡單、易用在這裡就不做贅述了，大家可以自行下載下傳體驗。其實最主要原因還是因為這個編輯器的導出PDF檔案功能，該編輯器導出的pdf檔案會根據markdown檔案的目錄生成pdf的導航目錄，這一點對于文檔檔案來說忒重要了！！！

六、總結

好了，至此任務基本上完成了，以後麻麻再也不用擔心我寫接口文檔啦！