使用apidocJs快速產生線上文檔的執行個體講解，apidocjs執行個體講解

使用apidocJs快速產生線上文檔的執行個體講解，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	選擇要解析的檔案，支援Regex。-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中的參數含義。

參數	描述
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：不能相加 */

從中可以看到name和age欄位的前面有些縮排，而且欄位顯示名為name和age。

以上這篇使用apidocJs快速產生線上文檔的執行個體講解就是小編分享給大家的全部內容了，希望能給大家一個參考，也希望大家多多支援幫客之家。