【API-doc】基本参数

安装node包

npm install apidoc -g

配置文件

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

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

一些注释参数

必备参数：用来标识apidoc需要解析的方法

@api {method} path [title]

类似宏定义 就是模板

@apiDefine name [title]
                     [description]

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

/**
 * @apiDefine tplName
 * @apiError params desc
 */

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

过时

@apiDeprecated

详细的描述

@apiDescription

错误返回

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

错误示例

@apiErrorExample [{type}] [title]
                 example

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

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

请求示例

@apiExample [{type}] title
            example

编组

@apiGroup name

接口名字 不会出现在doc

@apiName name

参数

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

私有接口

@apiPrivate

接口成功调用返回值

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

接口成功调用返回示例

@apiSuccessExample [{type}] [title]
                   example

生成接口文档

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

apidoc官方文档：apidoc文档