@api

被 @api 标记后, 会解析成 api 文档

@api {method} path [title]

Example:

/**
 * @api {get} /user/:id 获取用户详情
 */

@apiDefine

用来定义全局描述, 比如服务器内部错误描述, 权限描述等

@apiDefine name [title] [description]

Example:

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

@apiDescription

用于定义接口描述信息

@apiDescription text

Example:

/**
 * @api {get} /user/{id} 获取用户详情
 * @apiDescription 接口描述信息
 * 可以有多行
 * @apiUse MyError
 * @apiPermission admin
 */

@apiError

定义错误的描述信息

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

@apiErrorExample

错误信息示例

@apiErrorExample [{type}] [title] example

Example:

/**
 * @api {get} /user/{id} 获取用户详情
 * @apiDescription 接口描述信息
 * 可以有多行
 * @apiUse MyError
 * @apiPermission admin
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

@apiExample

api 请求示例

@apiExample [{type}] title
            example

Example:

/**
 * @api {get} /user/{id} 获取用户详情
 * @apiDescription 接口描述信息
 * 可以有多行
 * @apiUse MyError
 * @apiPermission admin
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 * @apiExample {curl} Example usage:
 *     curl -i http://dev.yyyyy.com/test/api/user/1024
 */

@apiGroup

定义方法文档块属于哪个组。组将用于生成输出中的主导航。结构定义不需要 @apigroup

@apiGroup name

Example:

/**
 * @api {get} /user/{id} 获取用户详情
 * @apiDescription 接口描述信息
 * 可以有多行
 * @apiGroup User
 * @apiUse MyError
 * @apiPermission admin
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 * @apiExample {curl} Example usage:
 *     curl -i http://dev.yyyyy.com/test/api/user/1024
 */

@apiHeader

描述传递给 API 头部的参数，例如用于授权。

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

Usage: @apiHeader (MyHeaderGroup) {String} authorization Authorization value.

Examples:

/**
 * @api {get} /user/:id
 * @apiHeader {String} Content-Type=application/json 浏览器以 json 方式发送数据给服务器
 * @apiHeader {String} Accept=application/json;charset=UTF-8 浏览器接收 json 数据
 */

使用 @apiDefine 定义全局 header 描述

/**
 * @apiDefine Header
 * @apiHeader {String} Content-Type=application/json 浏览器以 json 方式发送数据给服务器
 * @apiHeader {String} Accept=application/json;charset=UTF-8 浏览器接收 json 数据
 */

引入 header 描述

/**
 * @api {get} /user/{id} 获取用户详情
 * @apiDescription 接口描述信息
 * 可以有多行
 * @apiGroup User
 * @apiUse MyError
 * @apiPermission admin
 * @apiUse Header
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 * @apiExample {curl} Example usage:
 *     curl -i http://dev.yyyyy.com/test/api/user/1024
 */

@apiHeaderExample

header 参数 示例

@apiHeaderExample [{type}] [title]
                   example

Example:

/**
 * @apiDefine Header
 * @apiHeader {String} Content-Type=application/json 浏览器以 json 方式发送数据给服务器
 * @apiHeader {String} Accept=application/json;charset=UTF-8 浏览器接收 json 数据
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Content-Type": "Content-Type:application/json",
 *       "Accept": "Accept:application/json;charset=UTF-8"
 *     }
 */

@apiIgnore

用于定义未完成的接口描述, 不会被显示出来 必须在 @api 之前定义

@apiIgnore [hint]

Usage: @apiIgnore Not finished Method

Example:

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

@apiName

定义方法文档块的名称。将在生成的输出中使用子导航名。结构定义不需要 @apiName。

@apiName name

Example:

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

@apiParam

描述传递给 API 方法的参数

Usage: @apiParam (MyGroup) {Number} id Users unique ID.

Examples:

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

Example:

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

@apiPermission

定义接口权限

@apiPermission name

Example:

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

@apiPrivate

将 API 定义为私有的，允许创建两个 API 规范文档：一个不包含私有 api，另一个包含它们。

@apiPrivate

Usage: @apiPrivate

Command line usage to exclude/include private APIs: --private false|true

Example:

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

默认不显示私有接口

如果需要包含私有接口 使用一下命令

apidoc -i . -o apidoc/  --private true

@apiSampleRequest

定义是否显示接口调用相关部分 在与 apidoc.json 配置参数 [ sampleurl ]结合使用此参数

1. 如果在 apidoc.json 定义了 sampleUrl, 全部的 api 都会有一个测试表单
2. 如果没有定义 sampleUrl 字段, 只有标识了 @apiSampleRequest 的接口才会有测试表单
3. 如果定义了 sampleUrl 字段, api 中也有 @apiSampleRequest url, 且 url 已 http 开头, 则 api 的 url 会覆盖全局的 sampleUrl
5. 如果定义了 sampleUrl 字段, 但是某个 api 不需要测试表单, 则可以使用 @apiSampleRequest off

@apiSampleRequest url

定义 package.json

{
  "name": "xxx-api",
  "version": "1.0.0",
  "description": "xxx-api 接口文档",
  "apidoc": {
    "title": "",
    "url" : "",
    "sampleUrl":"http://dev.yyyyy.com/test/api"
  }
}

所有 api 都会出现 测试表单

同时定义测试 url, 且 @apiSampleRequest 已 http 开头, 则会覆盖 sampleUrl

@apiSampleRequest http://127.0.0.1/test/api/user

如果 @apiSampleRequest 只是定义 URI, 则会组合 apiSampleRequest 和 sampleUrl, 生成最终的 测试地址

@apiSampleRequest /user

@apiSuccessExample

定义正确的返回结果

@apiSuccessExample [{type}] [title]
                   example

Example:

/**
 * @apiDefine CODE_200 调用成功
 * @apiSuccess (Reponse 200) {number} code 200
 * @apiSuccess (Reponse 200) {json} [data='""']
 * @apiSuccessExample {json} Response 200 Example
 *   HTTP/1.1 200 OK
 *   {
 *     "rescode": 1200,
 * 		"message": "操作成功",
 * 		"timestamp": 1513920968552
 *   }
 */

@apiUse

定义 使用 @apiDefine 定义的全局定义

@apiUse name

Usage: @apiUse MySuccess

Example:

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

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

@apiVersion

定义 api 版本, 可用于对比不同的版本变化

@apiVersion version

Usage: @apiVersion 1.6.2

Example:

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

历史版本需要拷贝的 -apidoc.js 文件中