Laravel中使用apiDoc生成接口文档 （二）

Params

apidoc中最核心的东西就是参数（params）的书写，本节介绍apidoc中一些重要的params。

@api

@api定义一个特定的接口。如果一个注释块既不包含@apiDefine又没有包含@api参数，则apidoc会直接忽略这个注释块。这个参数在界面上表示一个接口区域块如下:

@api的书写格式为：

@api {method} path [title]

注意，[xxx]表示一个可选的参数，下同。

下表介绍了@api中的参数含义。

更多的配置项请参考apidoc官方文档站点。

@apiDefine

@apiDefine表示定义一个变量，该变量可以指代任意值（字符串、参数块），这个参数并且写在独立的代码块中。可以使用@apiUse来使用其定义的变量。

@apiDefine的书写格式为：

@apiDefine name [title] [description]

下表介绍了@apiDefine中的参数含义。

下面的代码定义一个错误块，然后在接口定义中引用使用这个错误块。多个不同接口可以引用同样的@apiDefine块，这也变成语言的变量功能一直。可以消除重复代码。

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

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

@apiDescription

用于@api代码块中，用于详尽地描述接口的功能。

@apiDescription的书写格式为：

@apiDescription text

text就是具体的描述内容，可以直接使用Markdown语法，这极大地丰富了其表现形式。

@apiGroup

表示接口所属的组，最直接的体现就是在侧边导航中将接口分在对用的组中。

@apiGroup的书写格式为：

@apiGroup name

name表示组名，可以是任意字符串。值得注意的是，name不支持中文，一旦输入中文，apidoc就会忽略这些中文字符。如果需要在界面中显示中文接口组名，只需要使用@apiDefine定义一个中文字符串，然后name用变量名替换即可。

/**
* @apiDefine group 测试
*/
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup group
*/

@apiName

表示接口的名字，应该在每个@api块中使用。可以生成一个Web锚点，快速定位接口位置。可以看到锚点（url的#后面的字符串）通常由groupName-apiName构成。

@apiName的书写格式为：

@apiName name

@apiUse

表示引用一个@apiDefine定义的值或块，相当于直接替换变量的值。

@apiUse的书写格式为：

@apiUse name

name是一个已定义的@apiDefine中的name，如果输入的name不存在，则会抛出类似下面的异常信息。

{ 
   File: 'src\\Demo1.java',
   Block: 4,
   Element: '@apiUse',
   Groupname: 'test',
   Definition: '@apiUse group',
   Example: '@apiDefine MyValidGroup Some title\n@apiUse MyValidGroup' 
}

下面是一个示例：

/**
 * @apiDefine test
 * @apiParam {Number} id Users unique ID.
 */
 
/**
 * @apiUse test
 * @apiParam {Number} name name.
 */

@apiParam

表示一个请求参数。

@apiParam的书写格式为：

/**
* @apiDefine test
* @apiParam {Number} id Users unique ID.
*/

/**
* @apiUse test
* @apiParam {Number} name name.
*/

下表介绍了@apiParam中的参数含义。

下面是一个简单的示例：

/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/
/**
* @api {post} /user/
* @apiParam {String} [firstname] 用户名（非必填）.
* @apiParam {String} lastname  用户姓（必填）.
*/

@apiSuccess

表示请求成功时的一个返回字段。

@apiSuccess的书写格式为：

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

@apiSuccess的参数含义与@apiParam一致，这里就不再做说明了。

@apiError

表示请求失败时的一个返回字段。

@apiError的书写格式为：

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

与apiSuccess的参数含义完全一致。

@apiParamExample

表示一个请求范例。

@apiParamExample的书写格式为：

@apiParamExample [{type}] [title] example

下面是一个简单的示例：

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

@apiSuccessExample

表示一个响应范例。其书写格式和参数含义与@apiParamExample完全一样。

@apiSampleRequest

表示一个接口测试块，可以根据定义的请求参数来生成一个表单，用来进行接口测试。

@apiSampleRequest的书写格式为：

@apiSampleRequest url

url可以与配置文件（apidoc.json）中的sampleUrl以及@api定义的path连接成一个完整的测试url。例如：

/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
* @apiSampleRequest /test
*/

生成的界面截图如下：

一些实际经验

下面介绍一下在实际使用过程发现的东西。

绝大部分地方可使用Markdown语法

在几乎所有的描述类字段处都可以使用符合Markdown语法的文本，可以使得文档形式更加美观。

/**
* @api {get} /user/:id
* @apiParam {String} rule
*
* - 规则1：不能使用小数
* - 规则2：不能相加
*/

从下图中可以看到name和age字段的前面有些缩进，而且字段显示名为name和age。