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

本文主要包含以下內(nèi)容：

1.介紹apidoc的基本概念

2.安裝、使用和簡單配置

3.一些特殊參數(shù)的含義及其使用

4.介紹一些使用經(jīng)驗(yàn)

前言

apidoc能做什么？

apidoc是一個(gè)輕量級(jí)的在線REST接口文檔生成系統(tǒng)，可以根據(jù)其特定的規(guī)則的代碼注釋來生成靜態(tài)網(wǎng)頁。首先看下它生成的文檔界面和風(fēng)格。

支持

apidoc支持多種主流的編碼語言，包括Java、C、C#、PHP和Javascript。一般情況下，語言會(huì)有多種注釋方法，例如就Java中有普通風(fēng)格的多行注釋和Javadoc風(fēng)格的注釋。apidoc并不支持所有的注釋，譬如Java僅中支持Javadoc風(fēng)格的注釋。首先要說明的是，apidoc并不具備語義識(shí)別能力，它不會(huì)發(fā)現(xiàn)代碼中是否有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平臺(tái)，在安裝apidoc之前，需要先安裝nodeJs。關(guān)于nodeJs的安裝，一搜一大把，不過為了文章的完整性，還是首先介紹一下Windows平臺(tái)下nodeJs的安裝。

nodeJs安裝

首先，去node.js官網(wǎng)上下載最新的安裝包，請(qǐng)下載自己對(duì)應(yīng)系統(tǒng)的安裝包。譬如筆者的操作系統(tǒng)是64位Windows操作系統(tǒng)，就下載下圖所示的node安裝包。

下載完畢后，按照一般的軟件安裝步驟安裝即可。由于筆者的計(jì)算機(jī)已經(jīng)安裝過了，在這里就不過細(xì)演示了。

按理來說，按照安裝步驟安裝完畢后，node環(huán)境也已經(jīng)配置好了，現(xiàn)在來驗(yàn)證一下node是否已正確安裝配置。

首先，打開Window Shell窗口。使用win+R快捷鍵打開運(yùn)行窗口，在文本框中輸入cmd并回車打開Windows Shell。

然后，在控制臺(tái)輸入node命令進(jìn)入node控制臺(tái)。

最后，運(yùn)行一個(gè)Hello World程序。在node控制臺(tái)中輸入console.info("hello world");，如果輸出如下圖所示的結(jié)果，則表示node安裝配置成功。

除了node之外，npm（node package manager，node安裝包管理器）也是很重要的，可以通過它來便捷地下載和安裝node應(yīng)用。在Windows Shell中輸入npm命令，如果出現(xiàn)如下圖所示的信息，則表示npm也正確安裝完畢。

apidoc安裝

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

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

等待一定時(shí)間（根據(jù)自身的網(wǎng)速）的下載和安裝之后，如果出現(xiàn)下圖所示的信息，則表示apidoc安裝成功。

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

初步使用

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

命令行

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

apidoc 參數(shù)

一些重要的參數(shù)如下表所示：

apidoc -i src/ -o apidoc/ # 可以通過搜索src目錄中的文件快速的生成文檔文件，并將這些文件放在apidoc目錄下。

apidoc -h # 顯示幫助信息

使用apidoc

一個(gè)典型的文件目錄結(jié)果如下圖所示。

其中：

apidoc.json：apidoc的項(xiàng)目級(jí)配置文件，它必須位于整個(gè)工程目錄頂層。

Demo1.java：用于演示的demo源文件，它可以位于整個(gè)工程目錄的頂層目錄及其子目錄下。apidoc會(huì)搜索整個(gè)工程目錄選擇所有可能的源文件。

apidoc.json和Demo1.java中包含的代碼分別如下：

{
 "name": "demo", 
 "version": "1.0.0",
 "description": "這是一個(gè)簡單的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.
 */

下面通過這個(gè)demo來介紹如何生成文檔文件。

首先，在Windows Shell中進(jìn)入apidoc工程目錄的上層目錄。例如筆者的apidoc的工程位于E:\workspaces\sublime\apidoc路徑下。在這個(gè)目錄中創(chuàng)建名為src的工程目錄，將apidoc.json和Demo1.java文件置于src目錄下。

然后，在Windows Shell中輸入apidoc -i src/ -o apidoc/命令，如果出現(xiàn)如下圖所示的Done結(jié)果，則表明文檔已經(jīng)生成，位于同級(jí)目錄的apidoc（與-o apidoc對(duì)應(yīng)）目錄下。

最后，打開apidoc目錄，可以看到如下圖所示的靜態(tài)Web文件。雙擊index.html就可以在瀏覽器中打開生成在線接口文檔網(wǎng)站。

這樣我們就成功地生成了一份在線接口文檔了，接下來就只要部署到任意Web容器（Apache、Tomcat等）就可以將接口文檔對(duì)外發(fā)布了，So easy！

配置

apidoc.json文件是項(xiàng)目級(jí)的配置文件，接下來簡單地介紹一下其中常用的配置項(xiàng)。

一個(gè)比較完整的配置文件如下：

{
 "name": "demo",
 "version": "1.0.0",
 "description": "這是一個(gè)簡單的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"
 ]
}

更多的配置項(xiàng)請(qǐng)參考apidoc官方文檔站點(diǎn)。

Params

apidoc中最核心的東西就是參數(shù)（params）的書寫，本節(jié)介紹apidoc中一些重要的params。

@api

@api定義一個(gè)特定的接口。如果一個(gè)注釋塊既不包含@apiDefine又沒有包含@api參數(shù)，則apidoc會(huì)直接忽略這個(gè)注釋塊。這個(gè)參數(shù)在界面上表示一個(gè)接口區(qū)域塊如下:

@api的書寫格式為：

@api {method} path [title]

注意，[xxx]表示一個(gè)可選的參數(shù)，下同。

下表介紹了@api中的參數(shù)含義。

更多的配置項(xiàng)請(qǐng)參考apidoc官方文檔站點(diǎn)。

@apiDefine

@apiDefine表示定義一個(gè)變量，該變量可以指代任意值（字符串、參數(shù)塊），這個(gè)參數(shù)并且寫在獨(dú)立的代碼塊中?？梢允褂?code>@apiUse來使用其定義的變量。

@apiDefine的書寫格式為：

@apiDefine name [title] [description]

下表介紹了@apiDefine中的參數(shù)含義。

下面的代碼定義一個(gè)錯(cuò)誤塊，然后在接口定義中引用使用這個(gè)錯(cuò)誤塊。多個(gè)不同接口可以引用同樣的@apiDefine塊，這也變成語言的變量功能一直?？梢韵貜?fù)代碼。

/**
 * @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就是具體的描述內(nèi)容，可以直接使用Markdown語法，這極大地豐富了其表現(xiàn)形式。

@apiGroup

表示接口所屬的組，最直接的體現(xiàn)就是在側(cè)邊導(dǎo)航中將接口分在對(duì)用的組中。

@apiGroup的書寫格式為：

@apiGroup name

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

/**
 * @apiDefine group 測(cè)試
 */

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup group
 */

@apiName

表示接口的名字，應(yīng)該在每個(gè)@api塊中使用?？梢陨梢粋€(gè)Web錨點(diǎn)，快速定位接口位置?？梢钥吹藉^點(diǎn)（url的#后面的字符串）通常由groupName-apiName構(gòu)成。

@apiName的書寫格式為：

@apiName name

@apiUse

表示引用一個(gè)@apiDefine定義的值或塊，相當(dāng)于直接替換變量的值。

@apiUse的書寫格式為：

@apiUse name 

name是一個(gè)已定義的@apiDefine中的name，如果輸入的name不存在，則會(huì)拋出類似下面的異常信息。

{ File: 'src\\Demo1.java',
 Block: 4,
 Element: '@apiUse',
 Groupname: 'test',
 Definition: '@apiUse group',
 Example: '@apiDefine MyValidGroup Some title\n@apiUse MyValidGroup' }

下面是一個(gè)示例：

/**
 * @apiDefine test
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @apiUse test
 * @apiParam {Number} name name.
 */

@apiParam

表示一個(gè)請(qǐng)求參數(shù)。

@apiParam的書寫格式為：

@apiParam [(group)] [{type}] [field=defaultValue] [description]

下表介紹了@apiParam中的參數(shù)含義。

下面是一個(gè)簡單的示例：

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {post} /user/
 * @apiParam {String} [firstname] 用戶名（非必填）.
 * @apiParam {String} lastname  用戶姓（必填）.
 */

@apiSuccess

表示請(qǐng)求成功時(shí)的一個(gè)返回字段。

@apiSuccess的書寫格式為：

@apiSuccess [(group)] [{type}] field [description]

@apiSuccess的參數(shù)含義與@apiParam一致，這里就不再做說明了。

@apiError

表示請(qǐng)求失敗時(shí)的一個(gè)返回字段。

@apiError的書寫格式為：

@apiError [(group)] [{type}] field [description]

與apiSuccess的參數(shù)含義完全一致。

@apiParamExample

表示一個(gè)請(qǐng)求范例。

@apiParamExample的書寫格式為：

@apiParamExample [{type}] [title] example

下面是一個(gè)簡單的示例：

/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *  {
 *  "id": 4711
 *  }
 */

@apiSuccessExample

表示一個(gè)響應(yīng)范例。其書寫格式和參數(shù)含義與@apiParamExample完全一樣。

@apiSampleRequest

表示一個(gè)接口測(cè)試塊，可以根據(jù)定義的請(qǐng)求參數(shù)來生成一個(gè)表單，用來進(jìn)行接口測(cè)試。

@apiSampleRequest的書寫格式為：

@apiSampleRequest url

url可以與配置文件（apidoc.json）中的sampleUrl以及@api定義的path連接成一個(gè)完整的測(cè)試url。例如：

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 * @apiSampleRequest /test
 */

生成的界面截圖如下：

一些實(shí)際經(jīng)驗(yàn)

下面介紹一下在實(shí)際使用過程發(fā)現(xiàn)的東西。

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

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

/**
 * @api {get} /user/:id
 * @apiParam {String} rule 
 *
 * - 規(guī)則1：不能使用小數(shù)
 * - 規(guī)則2：不能相加
 */

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

以上這篇使用apidocJs快速生成在線文檔的實(shí)例講解就是小編分享給大家的全部內(nèi)容了，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。