一、apidoc簡介

apidoc是一款可以有原始碼中的註釋直接自動生成api介面文件的工具，它幾乎支援目前主流的所有風格的註釋。例如：
Javadoc風格註釋(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等語言中使用)

/**
 * This is a comment.
 */

CoffeeScript

###
This is a comment.
###

Elixir

@apidoc """
This is a comment.
"""

Erlang (註釋中的‘%’是可選的)

%{
% This is a comment.
%}
 

Perl (Doxygen)

#**
# This is a comment.
#*

Python

"""
This is a comment.
"""

Ruby

=begin
This is a comment.
=end

Lua

--[[
This is a comment.
--]]

二、apidoc使用

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

npm install apidoc -g

執行：

apidoc -i myapp/ -o apidoc/ -t mytemplate/

2.1 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

2.2 配置(apidoc.json)

每次匯出介面文件都必須要讓apidoc讀取到apidoc.json檔案(如果未新增配置檔案，匯出報錯)，你可以在你專案的根目錄下新增apidoc.json檔案，這個檔案主要包含一些專案的描述資訊，比如標題、簡短的描述、版本等，你也可以加入一些可選的配置項，比如頁首、頁尾、模板等。
apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

如果你的專案中使用了package.json檔案(例如:node.js工程)，那麼你可以將apidoc.json檔案中的所有配置資訊放到package.json檔案中的apidoc引數中：
package.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
  }
}

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註釋引數

3.1 @api

【必填欄位】否則，apidoc會忽略該條註釋

@api {method} path [title]

引數列表:

引數	必填	描述
method	yes	請求型別:DELETE, GET, POST, PUT, ...更多
path	yes	請求路徑
title	no	介面標題

例：

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

3.2 @apiDefine

@apiDefine name [title]
                     [description]

定義註釋模組(類似於程式碼中定義一個常量)，對於一些通用可複用的註釋模組(例如:介面錯誤響應模組),只需要在原始碼中定義一次，便可以在其他註釋模組中隨便引用，最後在文件匯出時會自動替換所引用的註釋模組，定義之後您可以通過@apiUse來引入所定義的註釋模組。(注:可以同時使用@apiVersion來定義註釋模組的版本)
引數列表：

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

例:

/**
 * @apiDefine MyError
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

/**
 * @api {get} /user/:id
 * @apiUse MyError
 */

/**
 * @apiDefine admin User access only
 * This optional description belong to to the group admin.
 */

/**
 * @api {get} /user/:id
 * @apiPermission admin
 */

3.3 @apiDeprecated

@apiDeprecated [text]

標註一個介面已經被棄用
引數列表:

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

例：

**
 * @apiDeprecated
 */

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

3.4 @apiDescription

@apiDescription text

api介面的詳細描述
引數列表:

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

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

3.5 @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/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

3.6 @apiErrorExample

@apiErrorExample [{type}] [title]
                 example

介面錯誤返回示例(格式化輸出)
引數列表:

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

例:

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

3.7 @apiExample

@apiExample [{type}] title
            example

介面方式請求示例
引數列表:

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

/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://localhost/user/4711
 */

3.8 @apiGroup

@apiGroup name

定義介面所屬的介面組，雖然介面定義裡不需要這個引數，但是您應該在每個介面註釋裡都新增這個引數，因為匯出的介面文件會以介面組的形式導航展示。
引數列表:

引數	必填	描述
name	yes	介面組名稱(用於導航,不支援中文)

例：

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

3.9 @apiHeader

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

描述介面請求頭部需要的引數(功能類似@apiParam)
引數列表:

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

例:

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

3.10 @apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

請求頭部引數示例
引數列表:

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

例：

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

3.11 @apiIgnore

@apiIgnore [hint]

如果你需要使用該引數，請把它放到註釋塊的最前面。如果設定了該引數，那麼該註釋模組將不會被解析(當有些介面還未完成或未投入使用時，可以使用該欄位)
引數列表:

引數	必填	描述
hint	no	描介面忽略原因描述

例：

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

3.12 @apiName

@apiName name

介面名稱，每一個介面註釋裡都應該新增該欄位，在匯出的介面文件裡會已該欄位值作為導航子標題，如果兩個介面的@apiVersion和@apiName一樣，那麼有一個介面的註釋將會被覆蓋(介面文件裡不會展示)
引數列表:

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

例：

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

3.13 @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之間<br/>`{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/: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.
 */

3.14 @apiParamExample

@apiParamExample [{type}] [title]
                   example

請求體引數示例
引數列表:

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

例：

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

3.15 @apiPermission

允許訪問該介面的角色名稱

@apiPermission name

引數列表:

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

例：

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

3.16 @apiPrivate

@apiPrivate

定義私有介面，對於定義為私有的介面，可以在生成介面文件的時候，通過在命令列中設定引數 --private false|true來決定匯出的文件中是否包含私有介面
例：

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

3.17 @apiSampleRequest

@apiSampleRequest url

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

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

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

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 */

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

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */

關閉介面測試功能

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest off
 */

傳送測試請求到http://api.github.com/some_path/user/:id(由於沒有設定apidoc.json中的sampleUrl引數，所以只有當前介面有模擬測試功能)

Configuration parameter sampleUrl is not set
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

3.18 @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/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

包含(group):

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

返回引數中有物件:

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

3.19 @apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

返回成功示例
引數列表:

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

例：

/**
 * @api {get} /user/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */

[email protected]

@apiUse name

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

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

例:

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

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

3.21 @apiVersion

@apiVersion version

定義介面/註釋模組版本
引數列表:

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

例:

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

注：文中如有任何錯誤，請各位批評指正！

作者：liqingbiubiu
連結：https://www.jianshu.com/p/9353d5cc1ef8
來源：簡書
簡書著作權歸作者所有，任何形式的轉載都請聯絡作者獲得授權並註明出處。