nodejs下的apidoc 幫助接口文檔生成

原創 测试工程师_ 2020-02-20 18:12
在項目開發過程中，總會牽扯到接口文檔的設計與編寫，之前使用的都是office工具，寫一個文檔，總也是不夠漂亮和直觀。好在git上的開源大神提供了生成文檔的工具，so來介紹一下！
該工具是Nodejs的模塊，請務必在使用前安裝好nodejs環境！
工具名稱：apiDoc
項目地址：http://apidocjs.com/
apoDoc是從源碼的註釋中生成RestFul api 文檔，樣子還是蠻漂亮的……
自己寫了的ApiDoc文檔自動生成工具，避免每次寫完後手動執行生成代碼
支持的註釋樣式:
JavaDoc-Style
/**
* This is a comment.
*/
  • 1
  • 2
  • 3
CoffeeScript
###
This is a comment.
###
  • 1
  • 2
  • 3
Elixir
@apidoc """
This is a comment.
"""
  • 1
  • 2
  • 3
Erlang（%不是必須的）
%{% This is a comment.%}
  • 1
  • 2
  • 3
Perl (Doxygen)
#**# This is a comment.#*
  • 1
  • 2
  • 3
Python
"""
This is a comment.
"""
  • 1
  • 2
  • 3
Ruby
=begin
This is a comment.
=end
  • 1
  • 2
  • 3
安裝apiDoc
npm install apidoc -g
  • 1
使用npm命令安裝apidoc即可！
使用方式:
在命令行中輸入
apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/
  • 1
參數說明：
-f 文件過濾
使用正則表達式，表示哪些文件需要本轉換，不設置的情況下，默認爲.cs .dart .erl .go .java .js .php .py .rb .ts 後綴的文件。
-i 代碼文件夾
-o 輸出Api文檔的路徑
-t 使用模板文件的路徑，可以自定義輸出的模板
常用的命令格式如下:
apidoc -i myapp/ -o apidoc/
  • 1
配置
無package.json文件時，需要在代碼文件夾的根目錄下，創建apidoc.json文件。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
在該文件中即可配置apidoc
有package.json文件時，在package.json文件中添加”apidoc”: { }屬性即可。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"apidoc": {
"title": "Custom apiDoc browser title",
}
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
配置屬性如下:
name：項目名稱
version：項目版本
description：項目介紹
title：瀏覽器顯示的標題內容
url：endpoints的前綴，例如https://api.github.com/v1
sampleUrl：如果設置了，則在api文檔中出現一個測試用的from表單
header
title：導航文字包含header.md文件
filename：markdown-file 文件名
footer
title：導航文字包含header.md文件
filename：markdown-file 文件名
order：用於配置輸出 api-names/group-names 排序，在列表中的將按照列表中的順序排序，不在列表中的名稱將自動顯示。
模板的配置:
在apidoc.json中或在package.json中添加template屬性，將對模板進行特殊設置
forceLanguage：生成指定語言的文檔，簡體中文僅需設置”zh-cn”，支持的語言：https://github.com/apidoc/apidoc/tree/master/template/locales
withCompare：是否啓用與舊版本的比較功能，默認爲true
withGenerator：是否輸出生成信息，默認爲true
jQueryAjaxSetup：設置Ajax請求的默認值,參見http://api.jquery.com/jquery.ajaxsetup/
我使用的配置如下:
{
"name": "測試",
"version": "0.0.1",
"description": "API文檔測試",
"title": "API文檔測試",
"url" : "http://xxxxxxx",
"sampleUrl" : "http://xxxxxxxx",
"template":{
"forceLanguage":"zh-cn"
}
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
先來個demo試試：
在myapp文件夾下創建example.java
/**
* @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.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
之後執行
apidoc -i myapp/ -o apidoc/
  • 1
打開apidoc文件夾下的index.html即可看到效果。贊贊噠……
重頭戲來了，下面要講解一下apiDoc的註釋都是什麼含義
@api
@api {method} path [title]
  • 1
使用該註釋的才能被識別成爲文檔的一塊內容
path：請求路徑
title(可選)：標題
Example:
/**
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
@apiDefine
@apiDefine name [title]
[description]
  • 1
  • 2
定義重複內容，供其他模塊引用
name：重複模塊名
title（可選）：標題
description（可選）：說明
Example1:
/**
* @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
Example2:
/**
* @apiDefine admin User access only
* This optional description belong to to the group admin.
*/

/**
* @api {get} /user/:id
* @apiPermission admin
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
@apiDescription
@apiDescription text
  • 1
設置多行說明
text：多行說明內容
Example
/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
@apiError
@apiError [(group)] [{type}] field [description]
  • 1
請求錯誤參數
（group）（可選）：參數將以這個名稱分組，不設置的話，默認是Error 4xx
{type}（可選）：返回值類型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：返回值字段名稱
descriptionoptional（可選）：返回值字段說明
Example:
/**
* @api {get} /user/:id
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
  • 1
  • 2
  • 3
  • 4
@apiErrorExample
@apiErrorExample [{type}] [title]
example
  • 1
  • 2
錯誤返回信息樣例。
type（可選）：返回內容的格式
title（可選）：標題
example：樣例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
@apiExample
@apiExample [{type}] title
example
  • 1
  • 2
請求Api的測試樣例
{type}（可選）：請求方式類型
title：標題
example：樣例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiExample {curl} Example usage:
*/
  • 1
  • 2
  • 3
  • 4
  • 5
@apiGroup
@apiGroup name
  • 1
定義Api的分組
name：組名稱，也是導航的標題
Example:
/**
* @api {get} /user/:id
* @apiGroup User
*/
  • 1
  • 2
  • 3
  • 4
@apiHeader
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
  • 1
定義head參數
(group)（可選）：分組
{type}（可選）：類型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：變量名
[field]：定義變量，並標記變量是可選項
=defaultValue（可選）：默認值
description（optional）：變量說明
Examples:
/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
  • 1
  • 2
  • 3
  • 4
@apiHeaderExample
@apiHeaderExample [{type}] [title]
example
  • 1
  • 2
head參數樣例
{type}（可選）：請求方式類型
title：標題
example：樣例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
@apiIgnore
@apiIgnore [hint]
  • 1
忽略不發佈到文檔
hint（可選）：不發佈的原因
Example:
/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
  • 4
@apiName
@apiName name
  • 1
定義api名稱
name：api名稱
Example:
/**
* @api {get} /user/:id
* @apiName GetUser
*/
  • 1
  • 2
  • 3
  • 4
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]
  • 1
定義請求Api的參數
(group)（可選）：分組
{type}（可選）：類型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
{type{size}}（可選）：類型限定長度，例如：{string{..5}} 限定最大長度爲5個字符
{string{2..5}} 限定最短2個字符，最長5個字符
{number{100-999}} 限定數字在100-999之間
{type=allowedValues}（可選）：類型限定值，例如：{string=”small”}限定只允許傳遞small字符，
{string=”small”,”huge”} 限定只允許傳遞small或huge字符，
{number=1,2,3,99} 限定只允許傳1，2，3，99這四個數字
field：變量名
[field]：定義變量，並標記變量是可選項
=defaultValue（可選）：默認值
description（optional）：變量說明
Examples:
/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/

/**
* @api {post} /user/
* @apiParam {String} [firstname] Optional Firstname of the User.
* @apiParam {String} lastname Mandatory Lastname.
* @apiParam {String} country="DE" Mandatory with default value "DE".
* @apiParam {Number} [age=18] Optional Age with default 18.
*
* @apiParam (Login) {String} pass Only logged in users can post this.
* In generated documentation a separate
* "Login" Block will be generated.
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
@apiParamExample
@apiParamExample [{type}] [title]
example
  • 1
  • 2
請求參數樣例
{type}（可選）：請求方式類型
title：標題
example：樣例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
@apiPermission
@apiPermission name
  • 1
定義接口權限
name：權限名稱
Example:
/**
* @api {get} /user/:id
* @apiPermission none
*/
  • 1
  • 2
  • 3
  • 4
@apiSampleRequest
@apiSampleRequest url
  • 1
設置測試請求form，如果在apidoc.json或package.json中設置過了sampleUrl，則默認請求地址爲，sampleUrl+apipath，設置這個標籤則重寫測試請求路徑
url：測試地址，
樣例
@apiSampleRequest http://www.example.com 改變測試地址
@apiSampleRequest /my_test_path 在apipath中加前綴
@apiSampleRequest off 不顯示測試請求from
Examples:
默認請求的地址是http://api.github.com/user/:id
Configuration parameter sampleUrl: "http://api.github.com"/**
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
  • 4
需要將測試地址修改爲http://test.github.com/some_path/user/:id，則
Configuration parameter sampleUrl: "http://api.github.com"/**
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
  • 4
  • 5
當地址需要請求http://api.github.com/test/user/:id則
Configuration parameter sampleUrl: "http://api.github.com"/**
* @api {get} /user/:id
* @apiSampleRequest /test
*/
  • 1
  • 2
  • 3
  • 4
  • 5
不需要測試請求from
Configuration parameter sampleUrl: "http://api.github.com"/**
* @api {get} /user/:id
* @apiSampleRequest off
*/
  • 1
  • 2
  • 3
  • 4
  • 5
沒有設置sampleUrl時需要顯示測試請求from，並設置請求http://api.github.com/some_path/user/:id
Configuration parameter sampleUrl is not set
/**
* @api {get} /user/:id
*/
  • 1
  • 2
  • 3
  • 4
  • 5
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]
  • 1
請求成功返回的參數
（group）（可選）：參數將以這個名稱分組，不設置的話，默認是Error 4xx
{type}（可選）：返回值類型，例如：{Boolean}, {Number}, {String}, {Object}, {String[]}
field：返回值字段名稱
descriptionoptional（可選）：返回值字段說明
Example:
/**
* @api {get} /user/:id
* @apiSuccess (200) {String} firstname Firstname of the User.
* @apiSuccess (200) {String} lastname Lastname of the User.
*/
  • 1
  • 2
  • 3
  • 4
  • 5
@apiSuccessExample
@apiSuccessExample [{type}] [title]
example
  • 1
  • 2
請求成功返回數據樣例
{type}（可選）：請求方式類型
title：標題
example：樣例，可以是多行文本
Example:
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
@apiUse
@apiUse name
  • 1
使用在@apiDefine中定義的內容
name：在@apiDefine定義的name
Example:
/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/

/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
@apiVersion
@apiVersion version
  • 1
設定Api的版本號
version：版本號，格式(major.minor.patch)
Example:
/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/
  • 1
  • 2
  • 3
  • 4
以上就是apiDoc的介紹！謝謝各位看官……
附上一個樣例
user.java
/**
* @api {POST} /register 註冊用戶
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 用於註冊用戶
* @apiParam {String} account 用戶賬戶名
* @apiParam {String} password 密碼
* @apiParam {String} mobile 手機號
* @apiParam {int} vip = 0 是否註冊Vip身份 0 普通用戶 1 Vip用戶
* @apiParam {String} [recommend] 邀請碼
* @apiParamExample {json} 請求樣例：
* ?account=sodlinken&password=11223344&mobile=13739554137&vip=0&recommend=
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤
* @apiSuccessExample {json} 返回樣例:
* {"code":"0","msg":"註冊成功"}
*/

/**
* @api {POST} /login 用戶登錄
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 用於用戶登錄
* @apiParam {String} userName 用戶名
* @apiParam {String} password 密碼
* @apiParamExample {json} 請求樣例：
* ?userName=張三&password=11223344
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {String} code 0 代表無錯誤 1代表有錯誤
* @apiSuccess (200) {String} user 用戶信息
* @apiSuccess (200) {String} userId 用戶id
* @apiSuccessExample {json} 返回樣例:
* {"code":"0","msg":"登錄成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
*/

/**
* @api {GET} /users/:id 獲取用戶信息
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 獲取用戶信息
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤
* @apiSuccess (200) {String} name 真實姓名
* @apiSuccess (200) {String} mobile 手機號
* @apiSuccess (200) {String} birthday 生日
* @apiSuccess (200) {String} email 郵箱
* @apiSuccess (200) {String} summary 簡介
* @apiSuccess (200) {String} recommendCode 我的推薦碼
* @apiSuccess (200) {String} idCardNo 身份證號
* @apiSuccess (200) {String} memberState 會員狀態 0普通用戶 1VIP 2賬戶凍結
* @apiSuccess (200) {String} address 家庭住址
* @apiSuccess (200) {String} money 賬戶現金
* @apiSuccessExample {json} 返回樣例:
* {
* "code": 0,
* "msg": "",
* "name": "真實姓名",
* "mobile": 15808544477,
* "birthday": "1990-03-05",
* "email": "[email protected]",
* "summary": "簡介",
* "recommendCode": "我的推薦碼",
* "idCardNo": "身份證號",
* "memberState": 1,
* "address": "家庭住址",
* "money": "30.65"
* }
*/


/**
* @api {POST} /users/:id 修改(完善)用戶信息
* @apiGroup Users
* @apiVersion 0.0.1
* @apiDescription 修改(完善)用戶信息
* @apiParam (200) {String} [name] 真實姓名
* @apiParam (200) {String} [mobile] 手機號
* @apiParam (200) {String} [birthday] 生日
* @apiParam (200) {String} [email] 郵箱
* @apiParam (200) {String} [summary] 簡介
* @apiParam (200) {String} [idCardNo] 身份證號
* @apiParam (200) {String} [address] 家庭住址
* @apiSuccess (200) {String} msg 信息
* @apiSuccess (200) {int} code 0 代表無錯誤 1代表有錯誤
* @apiSuccessExample {json} 返回樣例:
* {"code":"0","msg":"修改成功"}
*/
測試工程師_
發佈了40 篇原創文章 · 獲贊 48 · 訪問量 9萬+
私信 關注
發表評論
所有評論
還沒有人評論，想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章

軟件測試的實質

  　　最近在讀《軟件測試》 一書，對叫這個名字的書多，我讀的是Ron Patton 寫的那本，對！2002年的中文版，已經十年了，雖然沒《軟件測試的藝術》那麼經典，那麼有深度，但絕對也是一本不錯的好書。讀到第三章“軟件的實質”，覺得確實

fnngj 2020-06-21 00:37:06

數據庫的五大約束條件

唯一約束：  如果有一列添加了唯一約束，那麼就代表如果這一列有值的話，           這個值必須唯一，不能跟其他的值一樣；  但是這一列允許位空值；           即：可以爲空值，但是一旦有值必須唯一；           

测试工程师_ 2020-06-20 17:52:58

TCP套接字端口複用SO_REUSEADDR

TCP套接字端口複用SO_REUSEADDR 下面建立的套接字都是tcp套接字 1.進程創建監聽套接字socket1，邦定一個指定端口，並接受了若干連接。那麼進程創建另外一個套接口socket2，並試圖邦定同一個端口時候，bind錯誤返

pfm685757 2020-06-15 05:39:28

WEB頁面中常見的四種控件的必須的測試

东方欲晓- 2020-02-20 23:29:01

各瀏覽器的鼠標位置測試

东方欲晓- 2020-02-20 23:29:01

如何進行兼容性測試

东方欲晓- 2020-02-20 23:28:49

軟件測試從業者 - 向戚繼光學管理

软件测试思想者 2020-02-20 23:28:17

軟件測試思想者 之 “功能測試概念 - 單字解析”

软件测试思想者 2020-02-20 23:28:17

關於測試工程師 linux的常用命令

测试工程师_ 2020-02-20 18:12:15

git 與 github

测试工程师_ 2020-02-20 18:12:15

軟件測試分類

fnngj 2020-02-20 17:35:42

bug的處理流程

fnngj 2020-02-20 17:35:41

軟件測試的實質

  　　最近在讀《軟件測試》 一書，對叫這個名字的書多，我讀的是Ron Patton 寫的那本，對！2002年的中文版，已經十年了，雖然沒《軟件測試的藝術》那麼經典，那麼有深度，但絕對也是一本不錯的好書。讀到第三章“軟件的實質”，覺得確實

fnngj 2020-06-21 00:37:06

數據庫的五大約束條件

唯一約束：  如果有一列添加了唯一約束，那麼就代表如果這一列有值的話，           這個值必須唯一，不能跟其他的值一樣；  但是這一列允許位空值；           即：可以爲空值，但是一旦有值必須唯一；           

测试工程师_ 2020-06-20 17:52:58

TCP套接字端口複用SO_REUSEADDR

TCP套接字端口複用SO_REUSEADDR 下面建立的套接字都是tcp套接字 1.進程創建監聽套接字socket1，邦定一個指定端口，並接受了若干連接。那麼進程創建另外一個套接口socket2，並試圖邦定同一個端口時候，bind錯誤返

pfm685757 2020-06-15 05:39:28