apiDoc 詳解 api接口文檔生成

安裝apidoc

官網

通過npm安裝，請提前安裝好npm

可以通過以下命令安裝apidoc:

npm install apidoc -g

配置(apidoc.json)

每次導出接口文檔都必須要讓apidoc讀取到apidoc.json文件(如果未添加配置文件，導出報錯)，你可以在你項目的根目錄下添加apidoc.json文件，這個文件主要包含一些項目的描述信息，比如標題、簡短的描述、版本等，你也可以加入一些可選的配置項，比如頁眉、頁腳、模板等。
apidoc.json

{
  "name": "系統接口文檔",
  "version": "0.0.1",
  "description": "文檔總描述",
  "title": "apidoc瀏覽器自定義標題",
  "url" : "文檔url地址"
}

如果你的項目中使用了package.json文件(例如:node.js工程)，那麼你可以將apidoc.json文件中的所有配置信息放到package.json文件中的apidoc參數中：
package.json

{
 "name": "系統接口文檔",
  "version": "0.0.1",
  "description": "文檔總描述",
  "apidoc": {
    "title": "apidoc瀏覽器自定義標題",
 	 "url" : "文檔url地址"
  }
}

apidoc.json配置項

參數	描述
name	工程名稱如果apidoc.json文件中沒有配置該參數，apidoc會嘗試從pakcage.json文件中讀取
version	版本如果apidoc.json文件中沒有配置該參數，apidoc會嘗試從pakcage.json文件中讀取
description	工程描述如果apidoc.json文件中沒有配置該參數，apidoc會嘗試從pakcage.json文件中讀取
title	瀏覽器標題
url	api路徑前綴例如:https://api.github.com/v1
sampleUrl	如果設置了該參數，那麼在文檔中便可以看到用於測試接口的一個表單(詳情可以查看參數@apiSampleReques)
header.title	頁眉導航標題
header.filename	頁眉文件名(markdown)
footer.title	頁腳導航標題
footer.filename	頁腳文件名(markdown)
order	接口名稱或接口組名稱的排序列表如果未定義，那麼所有名稱會自動排序"order": [ "Error", "Define", "PostTitleAndError", PostError"]

更多詳情

apidoc註釋參數

@api

【必填字段】否則，apidoc會忽略該條註釋

@api {method} path [title]

參數列表:

參數	必填	描述
method	yes	請求類型:DELETE, GET, POST, PUT, ...更多
path	yes	請求路徑
title	no	接口標題

例：

/**
* @api {get} /user/getUserById/:id 獲取用戶數據 - 根據id
*/

@apiErrorExample

接口錯誤返回示例(格式化輸出)

@apiErrorExample [{type}] [title]
                 example

參數列表:

參數	必填	描述
type	no	響應類型
title	no	示例標題
example	yes	示例詳情(兼容多行)

例：

/**
 *@api {get} /user/getUserById/:id 獲取用戶數據 - 根據id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

@apiDefine

定義註釋模塊(類似於代碼中定義一個常量)，對於一些通用可複用的註釋模塊(例如:接口錯誤響應模塊),只需要在源代碼中定義一次，便可以在其他註釋模塊中隨便引用，最後在文檔導出時會自動替換所引用的註釋模塊，定義之後您可以通過@apiUse來引入所定義的註釋模塊。(注:可以同時使用@apiVersion來定義註釋模塊的版本)

@apiDefine name [title] [description]

參數列表:

參數	必填	描述
name	yes	註釋模塊名稱(唯一)，不同@apiVersion可以定義相同名稱的註釋模塊
title	no	註釋模塊標題
description	no	註釋模塊詳細描述(詳細描述另起一行，可包含多行)

例：

/**
 * @apiDefine        FailResponse
 * @apiErrorExample  Response (fail):
 *     {
 *       "code":"error"
 *       "error_message": "錯誤內容"
 *     }
 */

/**
 * @apiDefine        SuccessResponse
 * @apiSuccessExample  Response (success):
 *     {
 *       "code":"0"
 *       "error_message": ""
 *       "data":"內容"
 *     }
 */

/**
 * @apiUse             SuccessResponse
 *
 * @apiUse             FailResponse
 */

@apiDeprecated

標註一個接口已經被棄用

@apiDeprecated [text]

參數列表:

參數	必填	描述
text	yes	多行文字描述

例：

/**
 * @apiDeprecated use now (#Group:Name).
 *
 * Example: to set a link to the GetDetails method of your group User
 * write (#User:GetDetails)
 */

@apiDescription

api接口的詳細描述

@apiDescription [text]

參數列表:

參數	必填	描述
text	yes	多行文字描述

例：

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

@apiError

錯誤返回參數

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

參數列表:

參數	必填	描述
(group)	no	所有的參數都會通過這個參數進行分組，如果未設置，默認值爲Error 4xx
{type}	no	返回類型，例如{Boolean}， {Number}， {String}， {Object}，{String[]}（字符串數組），…
field	yes	返回id
description	no	參數描述

例：

/**
 * @api {get} /user/getUserById/:id 獲取用戶數據 - 根據id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */
 
/**
 * @apiError (錯誤分組) {Object} xxx xxxxxxxx
 */

@apiExample

接口方式請求示例

@apiExample [{type}] title
            example

參數列表:

參數	必填	描述
type	no	請求內容格式
title	yes	示例標題
example	yes	示例詳情(兼容多行)

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://127.0.0.1/user/getUserById/1
 */

@apiGroup

定義接口所屬的接口組，雖然接口定義裏不需要這個參數，但是您應該在每個接口註釋裏都添加這個參數，因爲導出的接口文檔會以接口組的形式導航展示。

@apiGroup name

參數列表:

參數	必填	描述
name	yes	接口組名稱(用於導航,不支持中文)

例：

/**
 * @apiDefine User 用戶信息
 */
/**
 * @api {get} /user/getUserById/:id
 * @apiGroup User
 */

@apiParam

接口請求體參數

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

參數列表:

參數	必填	描述
(group)	no	所有的參數都會以該參數值進行分組(默認Parameter)
{type}	no	返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
{type{size}}	no	返回類型,同時定義參數的範圍{string{…5}}意爲字符串長度不超過5{string{2…5}}意爲字符串長度介於25之間 {number{100-999}}意爲數值介於100999之間
{type=allowedValues}	no	參數可選值{string=“small”}意爲字符串僅允許值爲"small"{string=“small”,“huge”}意爲字符串允許值爲"small"、“huge”{number=1,2,3,99}意爲數值允許值爲1、2、3、99{string {…5}=“small”,"huge"意爲字符串最大長度爲5並且值允許爲:“small”、“huge”
field	yes	參數名稱(定義該請求體參數爲必填)
[field]	yes	參數名稱(定義該請求體參數爲可選)
=defaultValue	no	參數默認值
description	no	參數描述

例：

/**
 * @api {get} /user/getUserById/: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.
 */

@apiHeader

描述接口請求頭部需要的參數(功能類似@apiParam)

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

參數列表:

參數	必填	描述
(group)	no	所有的參數都會以該參數值進行分組(默認Parameter)
{type}	no	返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	參數名稱(定義該頭部參數爲必填)
[field]	yes	參數名稱(定義該頭部參數爲可選)
=defaultValue	no	參數默認值
description	no	參數描述

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiHeaderExample

請求頭部參數示例

@apiHeaderExample [{type}] [title]
                   example

參數列表:

參數	必填	描述
type	no	請求內容格式
title	no	請求示例標題
example	yes	請求示例詳情(兼容多行)

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

@apiIgnore

如果你需要使用該參數，請把它放到註釋塊的最前面。如果設置了該參數，那麼該註釋模塊將不會被解析(當有些接口還未完成或未投入使用時，可以使用該字段)

@apiIgnore [hint]

參數列表:

參數	必填	描述
hint	no	描接口忽略原因描述

例：

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/getUserById/:id
 */

@apiName

接口名稱，每一個接口註釋裏都應該添加該字段，在導出的接口文檔裏會已該字段值作爲導航子標題，如果兩個接口的@apiVersion和@apiName一樣，那麼有一個接口的註釋將會被覆蓋(接口文檔裏不會展示)

@apiName name

參數列表:

參數	必填	描述
name	yes	接口名稱(相同接口版本下所有接口名稱應該是唯一的)

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiName getUserById
 */

@apiParamExample

請求體參數示例

@apiParamExample [{type}] [title]
                   example

參數列表:

參數	必填	描述
type	no	請求內容格式
title	no	請求示例標題
example	yes	請求示例詳情(兼容多行)

例：

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

@apiPermission

允許訪問該接口的角色名稱

@apiPermission name

參數列表:

參數	必填	描述
name	yes	允許訪問的角色名稱(唯一)

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiPermission none
 */

@apiPrivate

定義私有接口，對於定義爲私有的接口，可以在生成接口文檔的時候，通過在命令行中設置參數 --private false|true來決定導出的文檔中是否包含私有接口

@apiPrivate

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiPrivate
 */

@apiSampleRequest

設置了該參數後，導出的html接口文檔中會包含模擬接口請求的form表單；如果在配置文件apidoc.json中設置了參數sampleUrl,那麼導出的文檔中每一個接口都會包含模擬接口請求的form表單，如果既設置了sampleUrl參數，同時也不希望當前這個接口不包含模擬接口請求的form表單，可以使用@apiSampleRequest off來關閉。

@apiSampleRequest url

參數列表:

參數	必填	描述
url	yes	模擬接口請求的url@apiSampleRequest http://www.example.com意爲覆蓋apidoc.json中的sampleUrl參數@apiSampleRequest off意爲關閉接口測試功能

例：
發送測試請求到:http://api.github.com/user/getUserById/:id

/**
 * @api {get} /user/getUserById/:id
 */

發送測試請求到:http://test.github.com/some_path/user/getUserById/:id(覆蓋apidoc.json中的sampleUrl參數)

/**
 * @api {get} /user/getUserById/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */

關閉接口測試功能

/**
 * @api {get} /user/getUserById/:id
 * @apiSampleRequest off
 */

發送測試請求到http://api.github.com/some_path/user/getUserById/:id(由於沒有設置apidoc.json中的sampleUrl參數，所以只有當前接口有模擬測試功能)

/**
 * @api {get} /user/getUserById/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

@apiSuccess

接口成功返回參數

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

參數列表:

參數	必填	描述
(group)	no	所有的參數都會以該參數值進行分組,默認值:Success 200
{type}	no	返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	返回值(返回成功碼)
=defaultValue	no	參數默認值
description	no	參數描述

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

包含(group):

/**
 * @api {get} /user/getUserById/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname  Lastname of the User.
 */

返回參數中有對象:

/**
 * @api {get} /user/getUserById/:id
 * @apiSuccess {Boolean} active        Specify if the account is active.
 * @apiSuccess {Object}  profile       User profile information.
 * @apiSuccess {Number}  profile.age   Users age.
 * @apiSuccess {String}  profile.image Avatar-Image.
 */

返回參數中有數組：

/**
 * @api {get} /users
 * @apiSuccess {Object[]} profiles       List of user profiles.
 * @apiSuccess {Number}   profiles.age   Users age.
 * @apiSuccess {String}   profiles.image Avatar-Image.
 */

@apiSuccessExample

返回成功示例

@apiSuccessExample [{type}] [title]
                   example

參數列表:

參數	必填	描述
type	no	返回內容格式
title	no	返回示例標題
example	yes	返回示例詳情(兼容多行)

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "code":"0"
 *       "message": ""
 *       "data":"加密內容"
 *     }
 */

@apiUse

引入註釋模塊，如果當前模塊定義了@apiVersion,那麼版本相同或版本最近的註釋模塊會被引入

@apiUse name

參數列表:

參數	必填	描述
name	yes	引入註釋模塊的名稱

例：

/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */

/**
 * @api {get} /user/getUserById/:id
 * @apiUse MySuccess
 */

@apiVersion

定義接口/註釋模塊版本

@apiVersion version

參數列表:

參數	必填	描述
version	yes	版本號(支持APR版本規則:major.minor.patch)

例：

/**
 * @api {get} /user/getUserById/:id
 * @apiVersion 1.6.2
 */

小訣竅，筆者把接口中的通用部分利用apiDefine摘出來，放在一個公共文件中，之後可以利用apiUse去調用，或許部分註釋參數可以直接使用apiDefine即可調用。

生成接口文檔

當然你註釋參數寫好了之後它也不會幫你自動生成，你需要自己運行以下命令：
例：

apidoc -f ".*\\.php$"  -i ./application -o ./public/apidoc

參數列表:

參數	描述
-h, --help	查看幫助文檔
-f --file-filters	指定讀取文件的文件名過濾正則表達式(可指定多個)例如: apidoc -f “.*\.js$" -f ".*\\.ts$” 意爲只讀取後綴名爲js和ts的文件默認值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters	指定不讀取的文件名過濾正則表達式(可指定多個)例如:apidoc -e “.*\.js$” 意爲不讀取後綴名爲js的文件默認:’’
-i, --input	指定讀取源文件的目錄例如：apidoc -i myapp/ 意爲讀取myapp/目錄下面的源文件默認值:./
-o, --output	指定輸出文檔的目錄例如：apidoc -o doc/ 意爲輸出文檔到doc目錄下默認值:./doc/
-t, --template	指定輸出的模板文件例如:apidoc -t mytemplate/默認:path.join(__dirname, ‘…/template/’)(使用默認模板)
-c, --config	指定包含配置文件(apidoc.json)的目錄例如:apidoc -c config/默認:./
-p, --private	輸出的文檔中是否包含私有api例如:apidoc -p true 默認:false
-v, --verbose	是否輸出詳細的debug信息例如:apidoc -v true默認:false

之後你就能通過瀏覽器進行訪問了，比如我的是http://localhost/apidoc