- 介紹apidoc的基本概念
- 安裝、使用和簡單配置
- 一些特殊參數的含義及其使用
- 介紹一些使用經驗
前言
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.
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
* 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.
"""
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
安裝
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 參數
- 1
一些重要的參數如下表所示:
參數 | 描述 |
---|---|
-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目錄下。
- 1
apidoc -h # 顯示幫助信息
- 1
使用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"
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
/**
* @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.
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
下面通過這個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"
]
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
更多的配置項請參考apidoc官方文檔站點。
Params
apidoc中最核心的東西就是參數(params)的書寫,本節介紹apidoc中一些重要的params。
@api
@api
定義一個特定的接口。如果一個註釋塊既不包含@apiDefine
又沒有包含@api
參數,則apidoc會直接忽略這個註釋塊。這個參數在界面上表示一個接口區域塊如下:
@api
的書寫格式爲:
@api {method} path [title]
- 1
注意,[xxx]表示一個可選的參數,下同。
下表介紹了@api
中的參數含義。
參數 | 描述 |
---|---|
method | 請求的HTTP方法名,包括DELETE , GET, |
path | 請求的url path(不包括前綴) |
title | 接口名,用於接口索引。這個配置項會顯示在導航菜單中。 |
更多的配置項請參考apidoc官方文檔站點。
@apiDefine
@apiDefine
表示定義一個變量,該變量可以指代任意值(字符串、參數塊),這個參數並且寫在獨立的代碼塊中。可以使用@apiUse
來使用其定義的變量。
@apiDefine
的書寫格式爲:
@apiDefine name [title] [description]
- 1
下表介紹了@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
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
@apiDescription
用於@api
代碼塊中,用於詳盡地描述接口的功能。
@apiDescription
的書寫格式爲:
@apiDescription text
- 1
text就是具體的描述內容,可以直接使用Markdown語法,這極大地豐富了其表現形式。
@apiGroup
表示接口所屬的組,最直接的體現就是在側邊導航中將接口分在對用的組中。
@apiGroup
的書寫格式爲:
@apiGroup name
- 1
name表示組名,可以是任意字符串。值得注意的是,name不支持中文,一旦輸入中文,apidoc就會忽略這些中文字符。如果需要在界面中顯示中文接口組名,只需要使用@apiDefine
定義一箇中文字符串,然後name用變量名替換即可。
/**
* @apiDefine group 測試
*/
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup group
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
@apiName
表示接口的名字,應該在每個@api塊中使用。可以生成一個Web錨點,快速定位接口位置。可以看到錨點(url的#後面的字符串)通常由groupName-apiName構成。
@apiName
的書寫格式爲:
@apiName name
- 1
@apiUse
表示引用一個@apiDefine定義的值或塊,相當於直接替換變量的值。
@apiUse
的書寫格式爲:
@apiUse name
- 1
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' }
- 1
- 2
- 3
- 4
- 5
- 6
下面是一個示例:
/**
* @apiDefine test
* @apiParam {Number} id Users unique ID.
*/
/**
* @apiUse test
* @apiParam {Number} name name.
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
@apiParam
表示一個請求參數。
@apiParam
的書寫格式爲:
@apiParam [(group)] [{type}] [field=defaultValue] [description]
- 1
下表介紹了@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 用戶姓(必填).
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
@apiSuccess
表示請求成功時的一個返回字段。
@apiSuccess
的書寫格式爲:
@apiSuccess [(group)] [{type}] field [description]
- 1
@apiSuccess的參數含義與@apiParam一致,這裏就不再做說明了。
@apiError
表示請求失敗時的一個返回字段。
@apiError
的書寫格式爲:
@apiError [(group)] [{type}] field [description]
- 1
與apiSuccess的參數含義完全一致。
@apiParamExample
表示一個請求範例。
@apiParamExample
的書寫格式爲:
@apiParamExample [{type}] [title] example
- 1
參數 | 描述 |
---|---|
{type} | 表示請求數據的格式 |
title | 顯示在界面上的示例標題 |
example | 示例實體 |
下面是一個簡單的示例:
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
@apiSuccessExample
表示一個響應範例。其書寫格式和參數含義與@apiParamExample完全一樣。
@apiSampleRequest
表示一個接口測試塊,可以根據定義的請求參數來生成一個表單,用來進行接口測試。
@apiSampleRequest
的書寫格式爲:
@apiSampleRequest url
- 1
url可以與配置文件(apidoc.json)中的sampleUrl以及@api定義的path連接成一個完整的測試url。例如:
/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
* @apiSampleRequest /test
*/
- 1
- 2
- 3
- 4
- 5
生成的界面截圖如下:
一些實際經驗
下面介紹一下在實際使用過程發現的東西。
絕大部分地方可使用Markdown語法
在幾乎所有的描述類字段處都可以使用符合Markdown語法的文本,可以使得文檔形式更加美觀。
/**
* @api {get} /user/:id
* @apiParam {String} rule
*
* - 規則1:不能使用小數
* - 規則2:不能相加
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
對象類型的參數
如果請求的參數是一個對象,那此時因爲如果書寫呢?比如需要Post一個Person對象,Person中包括name、age字段,那麼可以這樣書寫。
/**
* @api {post} /user
* @apiName obj
* @apiParam {Object} person
* @apiParam {String} person.name 姓名
* @apiParam {Integer} person.age 年齡
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
從下圖中可以看到name和age字段的前面有些縮進,而且字段顯示名爲name和age。
使用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 *
/**
* @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.
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
* 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.
"""
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
安裝
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 參數
- 1
一些重要的參數如下表所示:
參數 | 描述 |
---|---|
-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目錄下。
- 1
apidoc -h # 顯示幫助信息
- 1
使用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"
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
/**
* @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.
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
下面通過這個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"
]
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
更多的配置項請參考apidoc官方文檔站點。
Params
apidoc中最核心的東西就是參數(params)的書寫,本節介紹apidoc中一些重要的params。
@api
@api
定義一個特定的接口。如果一個註釋塊既不包含@apiDefine
又沒有包含@api
參數,則apidoc會直接忽略這個註釋塊。這個參數在界面上表示一個接口區域塊如下:
@api
的書寫格式爲:
@api {method} path [title]
- 1
注意,[xxx]表示一個可選的參數,下同。
下表介紹了@api
中的參數含義。
參數 | 描述 |
---|---|
method | 請求的HTTP方法名,包括DELETE , GET, |
path | 請求的url path(不包括前綴) |
title | 接口名,用於接口索引。這個配置項會顯示在導航菜單中。 |
更多的配置項請參考apidoc官方文檔站點。
@apiDefine
@apiDefine
表示定義一個變量,該變量可以指代任意值(字符串、參數塊),這個參數並且寫在獨立的代碼塊中。可以使用@apiUse
來使用其定義的變量。
@apiDefine
的書寫格式爲:
@apiDefine name [title] [description]
- 1
下表介紹了@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
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
@apiDescription
用於@api
代碼塊中,用於詳盡地描述接口的功能。
@apiDescription
的書寫格式爲:
@apiDescription text
- 1
text就是具體的描述內容,可以直接使用Markdown語法,這極大地豐富了其表現形式。
@apiGroup
表示接口所屬的組,最直接的體現就是在側邊導航中將接口分在對用的組中。
@apiGroup
的書寫格式爲:
@apiGroup name
- 1
name表示組名,可以是任意字符串。值得注意的是,name不支持中文,一旦輸入中文,apidoc就會忽略這些中文字符。如果需要在界面中顯示中文接口組名,只需要使用@apiDefine
定義一箇中文字符串,然後name用變量名替換即可。
/**
* @apiDefine group 測試
*/
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup group
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
@apiName
表示接口的名字,應該在每個@api塊中使用。可以生成一個Web錨點,快速定位接口位置。可以看到錨點(url的#後面的字符串)通常由groupName-apiName構成。
@apiName
的書寫格式爲:
@apiName name
- 1
@apiUse
表示引用一個@apiDefine定義的值或塊,相當於直接替換變量的值。
@apiUse
的書寫格式爲:
@apiUse name
- 1
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' }
- 1
- 2
- 3
- 4
- 5
- 6
下面是一個示例:
/**
* @apiDefine test
* @apiParam {Number} id Users unique ID.
*/
/**
* @apiUse test
* @apiParam {Number} name name.
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
@apiParam
表示一個請求參數。
@apiParam
的書寫格式爲:
@apiParam [(group)] [{type}] [field=defaultValue] [description]
- 1
下表介紹了@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 用戶姓(必填).
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
@apiSuccess
表示請求成功時的一個返回字段。
@apiSuccess
的書寫格式爲:
@apiSuccess [(group)] [{type}] field [description]
- 1
@apiSuccess的參數含義與@apiParam一致,這裏就不再做說明了。
@apiError
表示請求失敗時的一個返回字段。
@apiError
的書寫格式爲:
@apiError [(group)] [{type}] field [description]
- 1
與apiSuccess的參數含義完全一致。
@apiParamExample
表示一個請求範例。
@apiParamExample
的書寫格式爲:
@apiParamExample [{type}] [title] example
- 1
參數 | 描述 |
---|---|
{type} | 表示請求數據的格式 |
title | 顯示在界面上的示例標題 |
example | 示例實體 |
下面是一個簡單的示例:
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
@apiSuccessExample
表示一個響應範例。其書寫格式和參數含義與@apiParamExample完全一樣。
@apiSampleRequest
表示一個接口測試塊,可以根據定義的請求參數來生成一個表單,用來進行接口測試。
@apiSampleRequest
的書寫格式爲:
@apiSampleRequest url
- 1
url可以與配置文件(apidoc.json)中的sampleUrl以及@api定義的path連接成一個完整的測試url。例如:
/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
* @apiSampleRequest /test
*/
- 1
- 2
- 3
- 4
- 5
生成的界面截圖如下:
一些實際經驗
下面介紹一下在實際使用過程發現的東西。
絕大部分地方可使用Markdown語法
在幾乎所有的描述類字段處都可以使用符合Markdown語法的文本,可以使得文檔形式更加美觀。
/**
* @api {get} /user/:id
* @apiParam {String} rule
*
* - 規則1:不能使用小數
* - 規則2:不能相加
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
對象類型的參數
如果請求的參數是一個對象,那此時因爲如果書寫呢?比如需要Post一個Person對象,Person中包括name、age字段,那麼可以這樣書寫。
/**
* @api {post} /user
* @apiName obj
* @apiParam {Object} person
* @apiParam {String} person.name 姓名
* @apiParam {Integer} person.age 年齡
*/
- 1
- 2
- 3
- 4
- 5
- 6
- 7
從下圖中可以看到name和age字段的前面有些縮進,而且字段顯示名爲name和age。