使用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來快速安裝。

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

等待必定時間（根據自身的網速）的下載和安裝以後，若是出現下圖所示的信息，則表示apidoc安裝成功。

二、在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/