RESTful web API Documentation Generator. http://apidocjs.com

入門

前言

本文檔中的所有示例都使用Javadoc-Style（可用於C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他支持Javadoc的語言）：

/**
 * This is a comment.
 */

安裝

npm install apidoc -g

配置（apidoc.json）

apidoc.json項目中的可選項root dir包含有關項目的常用信息，如標題，簡短說明，版本和配置選項，如頁眉/頁腳設置或模板特定選項。

"order": [
  "Error",
  "Define",
  "PostTitleAndError",
  "PostError"
]

|

在您的項目中，apidoc.json您可以添加頁眉和頁腳。

{ "header": { "title": "My own header title", "filename": "header.md" }, "footer": { "title": "My own footer title", "filename": "footer.md" } }

以下設置是特定於apiDoc的默認模板的。

apidoc.json實例

{
  "name": "項目名稱",
  "version": "1.0.0",
  "description": "介紹你的項目",
  "title": "瀏覽器標題文本",
  "url" : "Api路徑前綴，例如：http://localhost:8080",
  "sampleUrl": "所有方法都將具有API測試表單http://localhost:10086",
  "header": {
    "title": "頁頭標題Overview",
    "filename": "header.md"
  },
  "footer": {
    "title": "頁腳標題",
    "filename": "footer.md"
  },
  "template": {
    "withCompare": true,
    "withGenerator": true
  }
}

繼承

使用繼承，您可以定義文檔的可重用片段。

定義一個繼承塊，請使用apiDefine。
引用一個塊，使用apiUse。

繼承僅適用於1個父級

``/**

• **@apiDefine** UserNotFoundError *
• @apiError UserNotFound The id of the User was not found. *
• @apiErrorExample Error-Response:
• HTTP/1.1 404 Not Found
• {
• "error": "UserNotFound"
• } */

/**

• @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"
• } *
• **@apiUse** UserNotFoundError */

/**

• @api {put} /user/ Modify User information
• @apiName PutUser
• @apiGroup User *
• @apiParam {Number} id Users unique ID.
• @apiParam {String} [firstname] Firstname of the User.
• @apiParam {String} [lastname] Lastname of the User. *
• @apiSuccessExample Success-Response:
• HTTP/1.1 200 OK *
• **@apiUse** UserNotFoundError */``

版本

在示例中，在選擇框（主版本）上單擊右上角並選擇Compare changes to。

• 主導航標記全部用綠色條改變了方法。
• 每種方法都顯示與其前身相比的實際差異。
• 綠色標記添加的內容（在這種情況下，標題文本已更改，字段registered已添加）。
• 紅色標記已刪除的內容。

apidoc.json

{ "name": "example-versioning", "version": "0.2.0", "description": "apiDoc versioning example" }

為了避免API文檔隨時間變化而導致代碼膨脹，建議使用名為的單獨歷史文件_apidoc.js。在更改文檔塊之前，將舊文檔復制到此文件，apiDoc將自動包含歷史信息。

_apidoc.js（單獨歷史文件）

``/**

• @api {get} /user/:id Get User information
• **@apiVersion** 0.1.0
• @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"
• } */``

example.js（當前的項目文件）

``/**

• @api {get} /user/:id Get User information and Date of Registration.
• **@apiVersion 0.2.0**
• @apiName GetUser
• @apiGroup User *
• @apiParam {Number} id Users unique ID. *
• @apiSuccess {String} firstname Firstname of the User.
• @apiSuccess {String} lastname Lastname of the User.
• @apiSuccess {Date} registered Date of Registration. *
• @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"
• } */``

重要的是@apiVersion在每個文檔塊上設置版本。

該版本可以在每個塊上使用，也可以在繼承塊上使用。您不必在繼承塊上更改版本，解析器會自動檢查最近的前輩。

apiDoc-PARAMS

@api

@api {method} path [title]

需要！

如果沒有該指標，apiDoc解析器會忽略文檔塊。

唯一的例外是由@apiDefine它們定義的文檔塊 ，它們不是必需的[@api](https://my.oschina.net/u/2396174)。

用法： @api {get} /user/:id Users unique ID.

例：

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

@apiDefine

@apiDefine name [title]
                     [description]

定義一個文檔塊以嵌入到@api塊或類似的api函數中@apiPermission。

@apiDefine 每塊只能使用一次

通過使用@apiUse定義的塊將被導入，或者使用標題和描述的名稱將被使用。

用於定義可重用的文檔塊。該塊可以包含在普通的api文檔塊中。使用@apiDefine允許您更好地組織復雜的文檔並避免復制經常性塊。

定義的塊可以包含所有的參數（像@apiParam），除了其他定義的塊。

用法： @apiDefine MyError

例：

/**
 * @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
 */

@apiDeprecated

@apiDeprecated [text]

將API方法標記為已棄用

用法： @apiDeprecated use now (#Group:Name).

例：

/**
 * @apiDeprecated
 */

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

@apiDescription

@apiDescription text

API方法的詳細說明。

用法： @apiDescription This is the Description.

例：

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

@apiError

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

錯誤返回參數。

用法： @apiError UserNotFound

例：

/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

@apiErrorExample

@apiErrorExample [{type}] [title]
                 example

錯誤返回消息的示例，輸出為預格式化代碼。

用法： @apiErrorExample {json} Error-Response: This is an example.

例：

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

@apiExample

@apiExample [{type}] title
            example

使用API??方法的示例。以預格式化的代碼輸出。

在端點描述的開始處使用它作為完整的示例。

用法： @apiExample {js} Example usage: This is an example.

例：

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

@apiGroup

@apiGroup name

應該始終使用。

定義方法文檔塊屬於哪個組。組將用於生成的輸出中的主導航。結構定義不需要@apiGroup。

用法： @apiGroup User

例：

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

@apiHeader

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

描述傳遞給你的參數API-Header，例如Authorization。

與@apiParam類似的操作，只有輸出高於參數。

用法： @apiHeader (MyHeaderGroup) {String} authorization Authorization value.

例子：

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

@apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

參數請求示例。

用法： @apiHeaderExample {json} Request-Example: { "content": "This is an example content" }

例：

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

@apiIgnore

@apiIgnore [hint]

將它放在塊的頂部。

一個塊@apiIgnore將不被解析。如果您在源代碼中保留過時或未完成的方法並且您不希望將其發布到文檔中，這是有用的。

用法： @apiIgnore Not finished Method

例：

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

@apiName

@apiName name

應該始終使用。

定義方法文檔塊的名稱。名稱將用於生成的輸出中的子導航。結構定義不需要@apiName。

用法： @apiName GetUser

例：

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

@apiParam

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

描述傳遞給你的參數API-Method。

用法： @apiParam (MyGroup) {Number} id Users unique ID.

可以與size組合：
{string {..5}="small","huge"}一個字符串，它具有最多5個字符，並且只包含“small”或“huge”字樣。 | | filed | 變量名。 | | [filed] | 帶括號的字段名稱將變量定義為可選。 | | = defaultValue 可選 | 參數的默認值。 | | description 可選 | 該領域的描述。 |

例子：

/**
 * @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.
 */

@apiParamExample

@apiParamExample [{type}] [title]
                   example

參數請求示例。

用法： @apiParamExample {json} Request-Example: { "content": "This is an example content" }

例：

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

@apiPermission

@apiPermission name

輸出權限名稱。如果名稱是用@apiDefine生成的文檔定義的，則包括附加的標題和說明。

用法： @apiPermission admin

例：

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

@apiPrivate

@apiPrivate

將API定義為私有的，以允許創建兩個API規範文檔：一個排除私有API和一個包含它們的私有API。

用法： @apiPrivate

用於排除/包含私有API的命令行用法： --private false|true

例：

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

@apiSampleRequest

@apiSampleRequest url

將此參數與apidoc.json配置參數sampleUrl結合使用。

如果sampleUrl設置，所有方法都將具有API測試表單（@api的端點將被附加）。
如果沒有sampleUrl，只有方法@apiSampleRequest會有一個表單。

如果@apiSampleRequest url在方法塊中設置，則此URL將用於請求（當它以http開頭時，它將覆蓋sampleUrl）。

如果sampleUrl已設置並且您不想使用測試表單的方法，請將其添加@apiSampleRequest off到文檔塊中。

用法： @apiSampleRequest http://test.github.com

覆蓋配置參數sampleUrl並追加@api url：
@apiSampleRequest http://www.example.com

前綴@api url：
@apiSampleRequest /my_test_path

如果配置參數sampleUrl被設置，則禁用API測試：
@apiSampleRequest off |

例子：

這會將api請求發送到http://api.github.com/user/:id

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

這會將api請求發送到http://test.github.com/some_path/user/:id
它會覆蓋sampleUrl。

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

這將發送api請求到http://api.github.com/test/user/:id
它擴展了sampleUrl。

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

這將禁用此api方法的api請求。

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

這會將api請求發送到http://api.github.com/some_path/user/:id
它僅激活對此方法的請求，因為sampleUrl未設置。

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

@apiSuccess

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

成功返回參數。

用法： @apiSuccess {String} firstname Firstname of the User.

例：

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

示例(group)，@ apiSuccessTitle提供更多組示例：

/**
 * @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.
 */

@apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

成功返回消息的示例，輸出為預格式化代碼。

用法： @apiSuccessExample {json} Success-Response: { "content": "This is an example content" }

例：

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

@apiUse

@apiUse name

包含一個帶有@apiDefine定義的塊。如果與@apiVersion相同或最近的前輩一起使用將被包括在內。

用法： @apiUse MySuccess

例：

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

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

@apiVersion

@apiVersion version

設置文檔塊的版本。版本也可以用於@apiDefine。

可以在生成的輸出中比較具有相同組和名稱的塊，但可以比較不同版本，以便您或前端開發人員可以追溯自上一版本以後API中發生的更改。

用法： @apiVersion 1.6.2

例：

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

更多手表版本示例。

完整的例子

這是一個復雜的例子inherit，versioning文件和歷史文件_apidoc.js，解釋在代碼和生成文檔中。

查看示例輸出

文件：

• _apidoc.js

// ------------------------------------------------------------------------------------------
// General apiDoc documentation blocks and old history blocks.
// ------------------------------------------------------------------------------------------

// ------------------------------------------------------------------------------------------
// Current Success.
// ------------------------------------------------------------------------------------------


// ------------------------------------------------------------------------------------------
// Current Errors.
// ------------------------------------------------------------------------------------------
/**
 * @apiDefine CreateUserError
 * @apiVersion 0.2.0
 *
 * @apiError NoAccessRight Only authenticated Admins can access the data.
 * @apiError UserNameTooShort Minimum of 5 characters required.
 *
 * @apiErrorExample  Response (example):
 *     HTTP/1.1 400 Bad Request
 *     {
 *       "error": "UserNameTooShort"
 *     }
 */


// ------------------------------------------------------------------------------------------
// Current Permissions.
// ------------------------------------------------------------------------------------------
/**
 * @apiDefinePermission admin Admin access rights needed.
 * Optionally you can write here further Informations about the permission.
 *
 * An "apiDefinePermission"-block can have an "apiVersion", so you can attach the block to a specific version.
 *
 * @apiVersion 0.3.0
 */


// ------------------------------------------------------------------------------------------
// History.
// ------------------------------------------------------------------------------------------
/**
 * @apiDefinePermission admin This title is visible in version 0.1.0 and 0.2.0
 * @apiVersion 0.1.0
 */

/**
 * @api {get} /user/:id Read data of a User
 * @apiVersion 0.2.0
 * @apiName GetUser
 * @apiGroup User
 * @apiPermission admin
 *
 * @apiDescription Here you can describe the function.
 * Multilines are possible.
 *
 * @apiParam {String} id The Users-ID.
 *
 * @apiSuccess {String} id         The Users-ID.
 * @apiSuccess {Date}   name       Fullname of the User.
 *
 * @apiError UserNotFound   The <code>id</code> of the User was not found.
 */

/**
 * @api {get} /user/:id Read data of a User
 * @apiVersion 0.1.0
 * @apiName GetUser
 * @apiGroup User
 * @apiPermission admin
 *
 * @apiDescription Here you can describe the function.
 * Multilines are possible.
 *
 * @apiParam {String} id The Users-ID.
 *
 * @apiSuccess {String} id         The Users-ID.
 * @apiSuccess {Date}   name       Fullname of the User.
 *
 * @apiError UserNotFound   The error description text in version 0.1.0.
 */

/**
 * @api {post} /user Create a User
 * @apiVersion 0.2.0
 * @apiName PostUser
 * @apiGroup User
 * @apiPermission none
 *
 * @apiDescription In this case "apiUse" is defined and used.
 * Define blocks with params that will be used in several functions, so you dont have to rewrite them.
 *
 * @apiParam {String} name Name of the User.
 *
 * @apiSuccess {String} id         The Users-ID.
 *
 * @apiUse CreateUserError
 */

• example.js

/**
 * @api {get} /user/:id Read data of a User
 * @apiVersion 0.3.0
 * @apiName GetUser
 * @apiGroup User
 * @apiPermission admin
 *
 * @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
 *
 * @apiParam {String} id The Users-ID.
 *
 * @apiExample Example usage:
 * curl -i http://localhost/user/4711
 *
 * @apiSuccess {String}   id            The Users-ID.
 * @apiSuccess {Date}     registered    Registration Date.
 * @apiSuccess {Date}     name          Fullname of the User.
 * @apiSuccess {String[]} nicknames     List of Users nicknames (Array of Strings).
 * @apiSuccess {Object}   profile       Profile data (example for an Object)
 * @apiSuccess {Number}   profile.age   Users age.
 * @apiSuccess {String}   profile.image Avatar-Image.
 * @apiSuccess {Object[]} options       List of Users options (Array of Objects).
 * @apiSuccess {String}   options.name  Option Name.
 * @apiSuccess {String}   options.value Option Value.
 *
 * @apiError NoAccessRight Only authenticated Admins can access the data.
 * @apiError UserNotFound   The <code>id</code> of the User was not found.
 *
 * @apiErrorExample Response (example):
 *     HTTP/1.1 401 Not Authenticated
 *     {
 *       "error": "NoAccessRight"
 *     }
 */
function getUser() { return; }

/**
 * @api {post} /user Create a new User
 * @apiVersion 0.3.0
 * @apiName PostUser
 * @apiGroup User
 * @apiPermission none
 *
 * @apiDescription In this case "apiUse" is defined and used.
 * Define blocks with params that will be used in several functions, so you dont have to rewrite them.
 *
 * @apiParam {String} name Name of the User.
 *
 * @apiSuccess {String} id         The new Users-ID.
 *
 * @apiUse CreateUserError
 */
function postUser() { return; }

/**
 * @api {put} /user/:id Change a new User
 * @apiVersion 0.3.0
 * @apiName PutUser
 * @apiGroup User
 * @apiPermission none
 *
 * @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiUse"
 *
 * @apiParam {String} name Name of the User.
 *
 * @apiUse CreateUserError
 */
function putUser() { return; }

• apidoc.json

{
"name": "apidoc-example",
"version": "0.3.0",
"description": "apiDoc example project",
"title": "Custom apiDoc browser title",
"url": "https://api.github.com/v1",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
},
"order": [
"GetUser",
"PostUser"
],
"template": {
"withCompare": true,
"withGenerator": true
}
}

apiDoc構建源代碼註釋的接口文檔