apiDoc 参数标签说明（完整速查）

apiDoc 使用内联注释为 RESTful API 自动生成文档。以下为所有官方支持的参数与其说明。

@api

定义 API 方法的基本信息

@api {method} path title

method：请求方法，如 GET、POST、PUT、DELETE 等
path：请求路径，例如 /user/:id
title：简短标题（显示在文档中）

📘 示例：

@api {get} /user/:id Get user info

@apiBody

定义请求体参数

@apiBody [{type}] [field=defaultValue] [description]

{type} 参数类型（如 String, Number, Object, String[]）
[field] 可选字段（方括号表示可选）
=defaultValue 默认值
description 参数说明

📘 示例：

@apiBody {String} lastname Mandatory Lastname.
@apiBody {Object} [address] Optional address object.
@apiBody {String} [address[city]] Optional city.

@apiDefine

定义可复用的文档块

@apiDefine name [title] [description]

name：唯一标识
title：简短标题
description：多行描述

📘 示例：

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

@apiDeprecated

标记接口为弃用状态

@apiDeprecated [text]

text：提示文本，可带链接到新方法

📘 示例：

@apiDeprecated use now (#User:GetDetails)

@apiDescription

描述接口详细说明

@apiDescription text

📘 示例：

@apiDescription This is the Description.
It is multiline capable.

@apiError

定义错误返回参数

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

📘 示例：

@apiError UserNotFound The id of the User was not found.

@apiErrorExample

定义错误返回示例

@apiErrorExample [{type}] [title]
example

📘 示例：

@apiErrorExample {json} Error-Response:
    HTTP/1.1 404 Not Found
    { "error": "UserNotFound" }

@apiExample

定义接口使用示例

@apiExample [{type}] title
example

📘 示例：

@apiExample {curl} Example usage:
    curl -i http://localhost/user/4711

@apiGroup

定义所属分组

@apiGroup name

📘 示例：

@apiGroup User

@apiHeader

定义请求头参数

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

📘 示例：

@apiHeader {String} access-key Users unique access-key.

@apiHeaderExample

定义请求头示例

@apiHeaderExample [{type}] [title]
example

📘 示例：

@apiHeaderExample {json} Header-Example:
    {
      "Accept-Encoding": "gzip, deflate"
    }

@apiIgnore

忽略当前文档块

@apiIgnore [hint]

📘 示例：

@apiIgnore Not finished method

@apiName

定义接口唯一名称

@apiName name

📘 示例：

@apiName GetUser

@apiParam

定义请求参数

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

📘 示例：

@apiParam {Number} id Users unique ID.
@apiParam {String} [firstname] Optional firstname.
@apiParam {String} country="DE" Mandatory with default.

@apiParamExample

定义参数请求示例

@apiParamExample [{type}] [title]
example

📘 示例：

@apiParamExample {json} Request-Example:
    { "id": 4711 }

@apiPermission

定义权限要求

@apiPermission name

📘 示例：

@apiPermission admin

@apiPrivate

标记接口为私有（可过滤）

@apiPrivate

@apiQuery

定义查询参数（?query）

@apiQuery [{type}] [field=defaultValue] [description]

📘 示例：

@apiQuery {Number} id Users unique ID.
@apiQuery {String} [sort="asc"] Sort order.

@apiSampleRequest

定义接口测试请求 URL

@apiSampleRequest url

📘 示例：

@apiSampleRequest http://test.github.com/some_path/

@apiSuccess

定义成功返回参数

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

📘 示例：

@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname  Lastname of the User.

@apiSuccessExample

定义成功返回示例

@apiSuccessExample [{type}] [title]
example

📘 示例：

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

@apiUse

引用定义块（@apiDefine）

@apiUse name

📘 示例：

@apiDefine MySuccess
@apiSuccess {String} firstname User firstname.

@apiUse MySuccess

@apiVersion

定义接口版本

@apiVersion version

📘 示例：

@apiVersion 1.6.2

附录：常用标签速查表

标签	作用	示例
`@api`	定义接口	`@api {get} /user/:id`
`@apiName`	唯一名称	`@apiName GetUser`
`@apiGroup`	所属分组	`@apiGroup User`
`@apiParam`	请求参数	`@apiParam {Number} id Users unique ID.`
`@apiBody`	请求体参数	`@apiBody {String} name Username.`
`@apiQuery`	查询参数	`@apiQuery {String} keyword Search term.`
`@apiHeader`	Header 参数	`@apiHeader {String} token Auth token.`
`@apiSuccess`	成功返回字段	`@apiSuccess {String} name Username.`
`@apiError`	错误返回字段	`@apiError NotFound User not found.`
`@apiVersion`	版本号	`@apiVersion 1.0.0`