api规范PHP,api及文档编写规范

# 安装apidoc

> 团队成员无特殊需求一律使用[apidoc]([https://www.jianshu.com/p/34eac66b47e3])

> 通过npm安装，请提前安装好npm

可以通过以下命令安装apidoc:

```

npm install apidoc -g

```

# 配置(apidoc.json)

每次导出接口文档都必须要让apidoc读取到apidoc.json文件(如果未添加配置文件，导出报错)，你可以在你项目的根目录下添加apidoc.json文件，这个文件主要包含一些项目的描述信息，比如标题、简短的描述、版本等，你也可以加入一些可选的配置项，比如页眉、页脚、模板等。

`apidoc.json`

```

{

"name": "系统接口文档",

"version": "0.0.1",

"description": "文档总描述",

"title": "apidoc浏览器自定义标题",

"url" : "文档url地址"

}

```


# apidoc注释参数

## @api

【必填字段】否则，apidoc会忽略该条注释

```

@api {method} path [title]

```


例：

```

/**

* @api {get} /user/getUserById/:id 获取用户数据 - 根据id

*/

```

## @apiErrorExample

接口错误返回示例(格式化输出)

```

@apiErrorExample [{type}] [title]

example

```


```

/**

*@api {get} /user/getUserById/:id 获取用户数据 - 根据id

* @apiErrorExample {json} Error-Response:

* HTTP/1.1 404 Not Found

* {

* "error": "UserNotFound"

* }

*/

```

## @apiDefine

定义注释模块(类似于代码中定义一个常量)，对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次，便可以在其他注释模块中随便引用，最后在文档导出时会自动替换所引用的注释模块，定义之后您可以通过@apiUse来引入所定义的注释模块。(注:可以同时使用@apiVersion来定义注释模块的版本)

```

@apiDefine name [title] [description]

```


例：

```

/**

* @apiDefine FailResponse

* @apiErrorExample Response (fail):

* {

* "code":"error"

* "error_message": "错误内容"

* }

*/

/**

* @apiDefine SuccessResponse

* @apiSuccessExample Response (success):

* {

* "code":"0"

* "error_message": ""

* "data":"内容"

* }

*/

/**

* @apiUse SuccessResponse

*

* @apiUse FailResponse

*/

```

## @apiDeprecated

标注一个接口已经被弃用

```

@apiDeprecated [text]

```

例：

```

/**

* @apiDeprecated use now (#Group:Name).

*

* Example: to set a link to the GetDetails method of your group User

* write (#User:GetDetails)

*/

```

## @apiDescription

api接口的详细描述

```

@apiDescription [text]

```

例：

```

/**

* @apiDescription This is the Description.

* It is multiline capable.

*

* Last line of Description.

*/

```

## @apiError

错误返回参数

```

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

```


```

例：

/**

* @api {get} /user/getUserById/:id 获取用户数据 - 根据id

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

*/

/**

* @apiError (错误分组) {Object} xxx xxxxxxxx

*/

```

## @apiExample

接口方式请求示例

```

@apiExample [{type}] title

example

```


例：

```

/**

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

* @apiExample {curl} Example usage:

* curl -i http://127.0.0.1/user/getUserById/1

*/

```

## @apiGroup

定义接口所属的接口组，虽然接口定义里不需要这个参数，但是您应该在每个接口注释里都添加这个参数，因为导出的接口文档会以接口组的形式导航展示。

```

@apiGroup name

```

例：

```

/**

* @apiDefine User 用户信息

*/

/**

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

* @apiGroup User

*/

```

## @apiParam

```

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

```


```

/**

* @api {get} /user/getUserById/: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.

*/

```

## @apiHeader

描述接口请求头部需要的参数(功能类似`@apiParam`)

```

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

```


例：

```

/**

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

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

*/

```

## @apiHeaderExample

请求头部参数示例

```

@apiHeaderExample [{type}] [title]

example

```


例：

```

/**

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

* @apiHeaderExample {json} Header-Example:

* {

* "Accept-Encoding": "Accept-Encoding: gzip, deflate"

* }

*/

```

## @apiName

接口名称，每一个接口注释里都应该添加该字段，在导出的接口文档里会已该字段值作为导航子标题，如果两个接口的`@apiVersion`和@`apiName`一样，那么有一个接口的注释将会被覆盖(接口文档里不会展示)

```

@apiName name

```

例：

```

/**

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

* @apiName getUserById

*/

```

## @apiParamExample

请求体参数示例

```

@apiParamExample [{type}] [title]

example

```


## @apiPermission

允许访问该接口的角色名称

```

@apiPermission name

```

例：

```

/**

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

* @apiPermission none

*/

```

## @apiPrivate

定义私有接口，对于定义为私有的接口，可以在生成接口文档的时候，通过在命令行中设置参数 --private false|true来决定导出的文档中是否包含私有接口

```

@apiPrivate

```

例：

```

/**

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

* @apiPrivate

*/

```

## @apiSampleRequest

设置了该参数后，导出的html接口文档中会包含模拟接口请求的form表单；如果在配置文件apidoc.json中设置了参数sampleUrl,那么导出的文档中每一个接口都会包含模拟接口请求的form表单，如果既设置了sampleUrl参数，同时也不希望当前这个接口不包含模拟接口请求的form表单，可以使用@apiSampleRequest off来关闭。

```

@apiSampleRequest url

```

例：

```

/**

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

*/

```

## @apiSuccess

接口成功返回参数

```

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

```


例：

```

/**

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

* @apiSuccess {String} firstname Firstname of the User.

* @apiSuccess {String} lastname Lastname of the User.

*/

```

包含(group):

```

/**

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

* @apiSuccess (200) {String} firstname Firstname of the User.

* @apiSuccess (200) {String} lastname Lastname of the User.

*/

```

返回参数中有对象:

```

/**

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

* @apiSuccess {Boolean} active Specify if the account is active.

* @apiSuccess {Object} profile User profile information.

* @apiSuccess {Number} profile.age Users age.

* @apiSuccess {String} profile.image Avatar-Image.

*/

```

返回参数中有数组：

```

/**

* @api {get} /users

* @apiSuccess {Object[]} profiles List of user profiles.

* @apiSuccess {Number} profiles.age Users age.

* @apiSuccess {String} profiles.image Avatar-Image.

*/

```

## @apiSuccessExample

返回成功示例

```

@apiSuccessExample [{type}] [title]

example

```


```

/**

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

* @apiSuccessExample {json} Success-Response:

* HTTP/1.1 200 OK

* {

* "code":"0"

* "message": ""

* "data":"加密内容"

* }

*/

```

## @apiVersion

定义接口/注释模块版本

```

@apiVersion version

```

例：

```

/**

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

* @apiVersion 1.6.2

*/

```

# 生成接口文档

当然你注释参数写好了之后它也不会帮你自动生成，你需要自己运行以下命令：

例：

```

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

```