apiDoc入门、通过源代码中的API注释、创建文档（中文版）、安装、运行

野性酷女 2022-12-28 04:17 192阅读 0赞

# **API文档** #

## **RESTful Web API的内联文档** ##

### **apiDoc通过源代码中的API注释创建文档。** ###

**apiDoc使您能够将版本号附加到API，以便您可以轻松跟踪版本之间的更改。**

*  [演示版][Link 1]
 *  [入门][Link 2]
 *  [前言][Link 3]
 *  [安装][Link 4]
 *  [跑][Link 5]
 *  [命令行界面][Link 6]
 *  [GRUNT模块][GRUNT]
 *  [模板][Link 7]
 *  [延伸][Link 8]
 *  [配置（apidoc.json）][apidoc.json]
 *  [页眉页脚][Link 9]
 *  [例子][Link 10]
 *  [基本的][Link 11]
 *  [继承][Link 12]
 *  [版本控制][Link 13]
 *  [完整示例（一起）][Link 14]
 *  [apiDoc-Params][]
 *  [@api][api]
 *  [@apiDefine][apiDefine]
 *  [@api已弃用][api 1]
 *  [@api说明][api 2]
 *  [@apiError][apiError]
 *  [@apiErrorExample][apiErrorExample]
 *  [@apiExample][apiExample]
 *  [@apiGroup][apiGroup]
 *  [@apiHeader][apiHeader]
 *  [@apiHeaderExample][apiHeaderExample]
 *  [@apiIgnore][apiIgnore]
 *  [@apiName][apiName]
 *  [@apiParam][apiParam]
 *  [@apiParamExample][apiParamExample]
 *  [@apiPermission][apiPermission]
 *  [@api私人][api 3]
 *  [@apiSampleRequest][apiSampleRequest]
 *  [@api成功][api 4]
 *  [@apiSuccessExample][apiSuccessExample]
 *  [@apiUse][apiUse]
 *  [@apiVersion][apiVersion]
 *    
    [不推荐使用的参数][Link 15]

# **入门** #

## **安装** ##

npm install apidoc -g

## **运行** ##

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

创建dir中所有文件的apiDoc `myapp/`，使用dir中的模板`mytemplate/`，并将所有输出放入dir中`apidoc/`。

如果没有任何参数，apiDoc将从`.cs` `.dart` `.erl` `.go` `.java` `.js` `.php` `.py` `.rb` `.ts`当前目录（包括子目录）中的所有文件生成文档，并将输出写入`./doc/`。

## **命令行界面** ##

显示命令行参数：

apidoc -h

重要参数：

<table style="width:624px;"> 
 <thead> 
 <tr> 
 <th style="text-align:left;vertical-align:baseline;">参数</th> 
 <th style="text-align:left;vertical-align:baseline;">描述</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">-f，--file-filters</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">RegEx-Filter选择要分析的文件（可以使用许多-f）。默认<code>.cs</code>&nbsp;<code>.dart</code>&nbsp;<code>.erl</code>&nbsp;<code>.go</code>&nbsp;<code>.java</code>&nbsp;<code>.js</code>&nbsp;<code>.php</code>&nbsp;<code>.py</code>&nbsp;<code>.rb</code>&nbsp;<code>.ts</code>。 示例（仅解析.js和.ts文件）： <code>apidoc -f ".*\\.js$" -f ".*\\.ts$"</code></td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">-i，-输入</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">输入/源目录名。项目文件的位置。 例： <code>apidoc -i myapp/</code></td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">-o，-输出</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">输出目录名。放置生成的文档的位置。 例： <code>apidoc -o apidoc/</code></td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">-t，-模板</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">使用模板输出文件。您可以创建和使用自己的模板。 例： <code>apidoc -t mytemplate/</code></td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">-e，--exclude-filters</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">RegEx-Filter选择不应该分析的文件/目录（可以使用很多-e）。（默认值：[]） 示例： <code>apidoc -e node_modules</code></td> 
 </tr> 
 </tbody> 
</table>

## **GRUNT模块** ##

支持单独的grunt模块，请访问[github.com/apidoc/grunt-apidoc][github.com_apidoc_grunt-apidoc]  
或通过npm安装：

npm install grunt-apidoc --save-dev

## **模板** ##

apiDoc包括使用缺省模板[车把][Link 16]，[自举][Link 17]，[RequireJS][]和[jQuery的][jQuery]所生成的输出`api_data.js`并且`api_project.js`作为一个HTML页。

默认情况下，生成的apiDoc使用复杂的模板，该模板支持

*  版本控制：查看您的API的不同版本
 *  比较：查看两个API版本之间的更改

[查看默认演示][Link 18]

### 创建自己的 ###

你可以创建自己的模板，并使用apiDoc生成的文件`api_data.js`，`api_project.js`或JSON仅文件`api_data.json`，`api_project.json`。

在[https://github.com/apidoc/apidoc/tree/master/template][https_github.com_apidoc_apidoc_tree_master_template]上查看源代码

## **延伸** ##

可以使用您自己的参数扩展apiDoc（如果您需要的参数不可用）。请查看[apidoc / apidoc-core][apidoc _ apidoc-core]项目中的[lib / parsers /][lib _ parsers]， [lib / workers /][lib _ workers]和[lib / filters /][lib _ filters] 目录以获取示例。 拆分参数数据，使用所有找到的数据处理其他功能，并将数据简化为所需的内容。 `parser``worker``filter`

用法示例： `apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js`

**或[分叉][Link 19]整个项目并创建请求请求，以使apiDoc更好。**

## **配置（apidoc.json）** ##

`apidoc.json`项目根目录中的可选内容包括有关项目的常用信息，例如标题，简短描述，版本和配置选项（例如[页眉/页脚][Link 9]设置或模板特定的选项）。

[apidoc.json][apidoc.json 1]

{ "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的设置 ###

<table style="width:624px;"> 
 <thead> 
 <tr> 
 <th style="text-align:left;vertical-align:baseline;">名称</th> 
 <th style="text-align:left;vertical-align:baseline;">描述</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">名称</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">项目名称。 如果<code>apidoc.json</code>该字段不存在，则apiDoc尝试从确定值<code>package.json</code>。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">版</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">项目的版本。 如果<code>apidoc.json</code>该字段不存在，则apiDoc尝试从确定值<code>package.json</code>。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">描述</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">项目简介。 如果<code>apidoc.json</code>该字段不存在，则apiDoc尝试从确定值<code>package.json</code>。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">标题</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">浏览器标题文本。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">网址</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">api路径的前缀（端点），例如&nbsp;<code>https://api.github.com/v1</code></td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">sampleUrl</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">如果设置，则将显示用于测试api方法（发送请求）的表单。有关更多详细信息，请参见<a href="https://apidocjs.com/#param-api-sample-request" rel="nofollow">@apiSampleRequest</a>。</td> 
 </tr> 
 <tr> 
 <td colspan="2" style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">标头</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">&nbsp;&nbsp;&nbsp;&nbsp;标题</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">包含的header.md文件的导航文本。 （观看<a href="https://apidocjs.com/#headerfooter" rel="nofollow">页眉/页脚</a>）</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">&nbsp;&nbsp;&nbsp;&nbsp;文档名称</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">包含的header.md文件的文件名（markdown-file）。</td> 
 </tr> 
 <tr> 
 <td colspan="2" style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">页脚</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">&nbsp;&nbsp;&nbsp;&nbsp;标题</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">包含的footer.md文件的导航文本。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">&nbsp;&nbsp;&nbsp;&nbsp;文档名称</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">包含的footer.md文件的文件名（markdown文件）。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">订购</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">用于排序输出的api名称/组名称的列表。未定义的名称将自动显示在最后。 <pre style="margin-left:0px;"><code>"order": [ "Error", "Define", "PostTitleAndError", "PostError" ]</code></pre> </td> 
 </tr> 
 </tbody> 
</table>

### 模板特定设置 ###

以下设置特定于apiDoc的默认模板。

## **页眉页脚** ##

在您的项目中，`apidoc.json`您可以添加页眉和页脚。

标题将在导航中可见。文件名应为降价文本文件。

[apidoc.json][apidoc.json 1]

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

# **例子** #

可以在[Speakerdeck.com][]上找到介绍演示和一个小例子。

## **基本的** ##

在这个基本示例中，我们有一个小的项目文件和一个apidoc.json。

[查看示例输出][Link 20]

[apidoc.json][apidoc.json 2]

{ "name": "example", "version": "0.1.0", "description": "A basic apiDoc example" }

从`apidoc.json`apiDoc中获取项目的名称，版本和描述。  
该文件是`optional`（如果需要数据，则取决于模板）。

[example.js][]

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

文档块以开头`/**`和结尾`*/`。

本示例描述了`GET`一种通过用户的来请求用户信息的方法`id`。

`@api {get} /user/:id Request User information`是强制性的，没有`@api`apiDoc会忽略文档块。

`@apiName`必须是唯一名称，并且应始终使用。  
格式：*方法*\+*路径*（例如，获取+用户）

`@apiGroup` 应该始终使用，并用于将相关的API组合在一起。

所有其他字段都是可选的，请在[apiDoc-Params][]下查看其描述。

## **继承** ##

使用继承，您可以定义文档的可重用代码段。

[查看示例输出][Link 21]

[apidoc.json][apidoc.json 3]

{ "name": "example-inherit", "version": "0.1.0", "description": "apiDoc inherit example" }

[example.js][example.js 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 */

在此示例中，使用`UserNotFoundError`定义了名为的块`@apiDefine`。  
该块可以与一起使用多次`@apiUse UserNotFoundError`。

在生成的输出中，这两种方法`GET`和`PUT`都将具有完整的`UserNotFoundError`文档。

要定义继承块，请使用`apiDefine`。  
要引用一个块，请使用`apiUse`。 `apiGroup`并且`apiPermission`使用命令来（但在上下文中）不继承参数，仅继承标题和描述（与apiVersion结合使用）。

**继承仅适用于1个父级**，更多级别将使内联代码不可读，并且更改确实非常复杂。

## **版本控制** ##

apiDoc提供的一项有用功能是能够维护所有先前版本和最新版本的API文档。这样就可以将方法版本与其先前版本进行比较。因此，Frontend Developer可以简单地查看已更改的内容并相应地更新其代码。

[查看示例输出][Link 22]

在示例中，单击选择框（主版本）的右上角，然后选择`Compare all with predecessor`。

*  主导航用绿色条标记所有已更改的方法。
 *  每种方法都显示出与其前任相比的实际差异。
 *  绿色标记添加的内容（在这种情况下，标题文本已更改，字段`registered`已添加）。
 *  红色标记已删除的内容。

您可以将主版本（右上方）更改为以前的版本，然后将较旧的方法与以前的方法进行比较。

[apidoc.json][apidoc.json 3]

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

为了避免API文档随时间变化而导致代码膨胀，建议使用名为的单独历史记录文件`_apidoc.js`。在更改文档栏之前，请将旧文档复制到该文件，apiDoc将自动包括历史信息。

[\_apidoc.js][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][example.js 2]（您当前的项目文件）

/** * @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`在每个文档块上都设置版本。

该版本可用于每个块，也可用于继承块。您不必在继承块上更改版本，解析器会自动检查最近的前任版本。

## **完整的例子** ##

这是一个带有`inherit`，`versioning`文件和历史文件的复杂示例`_apidoc.js`，说明在代码和生成的文档内。

[查看示例输出][Link 18]

档案：

*  [\_apidoc.js][apidoc.js 1]
 *  [example.js][example.js 3]
 *  [apidoc.json][apidoc.json 1]

# **apiDoc-Params** #

结构参数如：

*  `@apiDefine`

用于定义可重用的文档块。此块可以包含在常规api文档块中。使用`@apiDefine`使您可以更好地组织复杂的文档，并避免重复的重复块。

定义的块可以具有所有参数（如`@apiParam`），**其他定义的块除外**。

## **@api** ##

@api {method} path [title]

**需要！**

如果没有该指示符，则apiDoc解析器将忽略文档记录块。

唯一的例外是由定义的文档块 `@apiDefine`，它们不是必需的`@api`。

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

例：

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

## **@apiDefine** ##

@apiDefine name [title]
                         [description]

定义要嵌入到文档块中`@api`或api函数之类的文档模块`@apiPermission`。

`@apiDefine` 每个方块只能使用一次

通过使用`@apiUse`已定义的块，将导入该块，或使用名称和标题和说明。

用法： `@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
     */

有关更多详细信息，请参见[继承示例][Link 12]。

## **@api已弃用** ##

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

## **@api说明** ##

@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标头的参数，例如用于授权。

*与[@apiParam][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方法的参数。

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

对于嵌套参数，请使用方括号符号（`[]`）。

<table style="width:624px;"> 
 <thead> 
 <tr> 
 <th style="text-align:left;vertical-align:baseline;">名称</th> 
 <th style="text-align:left;vertical-align:baseline;">描述</th> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">（组）可选的</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">所有参数将按此名称分组。 如果没有组，<code>Parameter</code>则设置默认值。 您可以使用<a href="https://apidocjs.com/#param-api-define" rel="nofollow">@apiDefine</a>设置标题和描述。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">{类型}可选的</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">参数类型，例如<code>{Boolean}</code>，<code>{Number}</code>，<code>{String}</code>，<code>{Object}</code>，<code>{String[]}</code>（字符串数组），...</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">{type {size}}可选的</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">有关变量大小的信息。 <code>{string{..5}}</code>最多5个字符的字符串。 <code>{string{2..5}}</code>最小的字符串&nbsp;2个字符，最多5个字符。 <code>{number{100-999}}</code>100到999之间的数字。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">{type = allowedValues}可选的</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">有关变量的允许值的信息。 <code>{string="small"}</code>一个只能包含单词“ small”（常量）的字符串。 <code>{string="small","huge"}</code>一个可以包含单词“ small”或“ huge”的字符串。 <code>{number=1,2,3,99}</code>一个允许值为1、2、3和99的数字。 可以与大小组合： <code>{string {..5}="small","huge"}</code>一个字符串，最多包含5个字符，并且仅包含单词“ small”或“ huge”。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">领域</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">栏位名称。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">[领域]</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">带括号的字段名称将变量定义为可选。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">字段[nestedField]</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">强制嵌套字段。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">=默认值可选的</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">参数默认值。</td> 
 </tr> 
 <tr> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;width:150px;">描述可选的</td> 
 <td style="border-color:#e0e0e0;text-align:left;vertical-align:top;">字段说明。</td> 
 </tr> 
 </tbody> 
</table>

例子：

/**
     * @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.
     *
     * @apiParam {Object} [address]         Optional nested address object.
     * @apiParam {String} [address[street]] Optional street and number.
     * @apiParam {String} [address[zip]]    Optional zip code.
     * @apiParam {String} [address[city]]   Optional city.
     */

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

## **@api私人** ##

@apiPrivate

将API定义为私有API，以允许创建两个API规范文档：一个排除私有API，另一个包括私有API。

用法： `@apiPrivate`

用于排除/包括私有API的命令行用法： `--private false|true`

例：

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

## **@apiSampleRequest** ##

@apiSampleRequest url

将此参数与apidoc.json配置参数[sampleUrl][]结合使用。

如果`sampleUrl`设置为，则所有方法都将具有api测试表单（将附加[@api][api]的端点）。  
如果不使用sampleUrl，则仅有的方法`@apiSampleRequest`将具有形式。

如果`@apiSampleRequest url`在方法块中设置了if ，则该网址将用于请求（当它以http开头时，它将覆盖sampleUrl）。

如果`sampleUrl`设置为if并且您不想要带有测试表单的方法，则将其添加`@apiSampleRequest off`到documentation块中。

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

例子：

这会将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/
     */

## **@api成功** ##

@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上的][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
     */

有关更多手表[版本控制示例][Link 13]。

[Link 1]: https://apidocjs.com/#demo
[Link 2]: https://apidocjs.com/#getting-started
[Link 3]: https://apidocjs.com/#preface
[Link 4]: https://apidocjs.com/#install
[Link 5]: https://apidocjs.com/#run
[Link 6]: https://apidocjs.com/#CLI
[GRUNT]: https://apidocjs.com/#grunt-module
[Link 7]: https://apidocjs.com/#template
[Link 8]: https://apidocjs.com/#extend
[apidoc.json]: https://apidocjs.com/#configuration
[Link 9]: https://apidocjs.com/#headerfooter
[Link 10]: https://apidocjs.com/#examples
[Link 11]: https://apidocjs.com/#example-basic
[Link 12]: https://apidocjs.com/#example-inherit
[Link 13]: https://apidocjs.com/#example-versioning
[Link 14]: https://apidocjs.com/#example-full
[apiDoc-Params]: https://apidocjs.com/#params
[api]: https://apidocjs.com/#param-api
[apiDefine]: https://apidocjs.com/#param-api-define
[api 1]: https://apidocjs.com/#param-api-deprecated
[api 2]: https://apidocjs.com/#param-api-description
[apiError]: https://apidocjs.com/#param-api-error
[apiErrorExample]: https://apidocjs.com/#param-api-error-example
[apiExample]: https://apidocjs.com/#param-api-example
[apiGroup]: https://apidocjs.com/#param-api-group
[apiHeader]: https://apidocjs.com/#param-api-header
[apiHeaderExample]: https://apidocjs.com/#param-api-header-example
[apiIgnore]: https://apidocjs.com/#param-api-ignore
[apiName]: https://apidocjs.com/#param-api-name
[apiParam]: https://apidocjs.com/#param-api-param
[apiParamExample]: https://apidocjs.com/#param-api-param-example
[apiPermission]: https://apidocjs.com/#param-api-permission
[api 3]: https://apidocjs.com/#param-api-private
[apiSampleRequest]: https://apidocjs.com/#param-api-sample-request
[api 4]: https://apidocjs.com/#param-api-success
[apiSuccessExample]: https://apidocjs.com/#param-api-success-example
[apiUse]: https://apidocjs.com/#param-api-use
[apiVersion]: https://apidocjs.com/#param-api-version
[Link 15]: https://apidocjs.com/deprecated.html
[github.com_apidoc_grunt-apidoc]: https://github.com/apidoc/grunt-apidoc
[Link 16]: http://handlebarsjs.com/
[Link 17]: http://twitter.github.io/bootstrap/
[RequireJS]: http://requirejs.org/
[jQuery]: http://jquery.com/
[Link 18]: https://apidocjs.com/example/
[https_github.com_apidoc_apidoc_tree_master_template]: https://github.com/apidoc/apidoc/tree/master/template
[apidoc _ apidoc-core]: https://github.com/apidoc/apidoc-core
[lib _ parsers]: https://github.com/apidoc/apidoc-core/tree/master/lib/parsers
[lib _ workers]: https://github.com/apidoc/apidoc-core/tree/master/lib/workers
[lib _ filters]: https://github.com/apidoc/apidoc-core/tree/master/lib/filters
[Link 19]: https://github.com/apidoc/apidoc
[apidoc.json 1]: https://apidocjs.com/source/example_full/apidoc.json
[Speakerdeck.com]: https://speakerdeck.com/rottmann/api-documentation
[Link 20]: https://apidocjs.com/example_basic/
[apidoc.json 2]: https://apidocjs.com/source/example_basic/apidoc.json
[example.js]: https://apidocjs.com/source/example_basic/example.js
[Link 21]: https://apidocjs.com/example_inherit/
[apidoc.json 3]: https://apidocjs.com/source/example_inherit/apidoc.json
[example.js 1]: https://apidocjs.com/source/example_inherit/example.js
[Link 22]: https://apidocjs.com/example_versioning/
[apidoc.js]: https://apidocjs.com/source/example_versioning/_apidoc.js
[example.js 2]: https://apidocjs.com/source/example_versioning/example.js
[apidoc.js 1]: https://apidocjs.com/source/example_full/_apidoc.js
[example.js 3]: https://apidocjs.com/source/example_full/example.js
[sampleUrl]: https://apidocjs.com/#configuration-settings-sample-url
[apiSuccessTitle]: https://apidocjs.com/#param-api-success-title