【API-doc】基本参数

(Updated: )
开发
, ,

安装node包

1
npm install apidoc -g

配置文件

1
2
3
4
5
6
7
{
  "name": "系统接口文档",
  "version": "0.0.1",
  "description": "文档总描述",
  "title": "apidoc浏览器自定义标题",
  "url" : "文档url地址"
}

或者直接在 package.json 里面加个apidoc的字段就好了。

一些注释参数

必备参数：用来标识apidoc需要解析的方法
1
@api {method} path [title]

类似宏定义 就是模板

1
2
@apiDefine name [title]
                     [description]

eg：定义好模板后，后面使用直接@apiUse就好了。

1
2
3
4
5
6
7
8
9
/**
 * @apiDefine tplName
 * @apiError params desc
 */

/**
 * @api {get} /user/:id
 * @apiUse tplName
 */
过时
1
@apiDeprecated
详细的描述
1
@apiDescription
错误返回
1
@apiError [(group)] [{type}] field [description]

错误示例

1
2
@apiErrorExample [{type}] [title]
                 example

eg：返回格式json，按照response后面的原格式输出

1
2
3
4
5
6
7
8
/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
请求示例
1
2
@apiExample [{type}] title
            example
编组
1
@apiGroup name

接口名字 不会出现在doc

1
@apiName name
参数
1
@apiParam [(group)] [{type}] [field=defaultValue] [description]

私有接口

1
@apiPrivate

接口成功调用返回值

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

接口成功调用返回示例

1
2
@apiSuccessExample [{type}] [title]
                   example

生成接口文档

1
apidoc -f ".*\\.php$"  -i ./app -o ./public/apidoc

apidoc官方文档：apidoc文档