# 安装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地址"
}
```
![](https://img.kancloud.cn/f2/cc/f2cc6f169a282b37ba5747dfb2557552_981x513.png)
# apidoc注释参数
## @api
【必填字段】否则,apidoc会忽略该条注释
```
@api {method} path [title]
```
![](https://img.kancloud.cn/7a/ee/7aee111bd0079f097810f7c2e4298f1d_814x189.png)
例:
```
/**
* @api {get} /user/getUserById/:id 获取用户数据 - 根据id
*/
```
## @apiErrorExample
接口错误返回示例(格式化输出)
```
@apiErrorExample [{type}] [title]
example
```
![](https://img.kancloud.cn/0b/79/0b7931afb9ce5bfd8e53493ac9b59f10_796x190.png)
```
/**
*@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]
```
![](https://img.kancloud.cn/71/07/7107a542d037ac6950eadb78c5f71c74_798x179.png)
例:
```
/**
* @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]
```
![](https://img.kancloud.cn/c0/b0/c0b0506acd1fce13fb5f60676e7d603f_799x316.png)
```
例:
/**
* @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
```
![](https://img.kancloud.cn/10/da/10dabd65f67f19fec85577c6818e9bff_799x182.png)
例:
```
/**
* @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]
```
![](https://img.kancloud.cn/13/6a/136a2c0c0d3a444bcf2190b8372c47ca_783x476.png)
```
/**
* @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]
```
![](https://img.kancloud.cn/65/2f/652fa009327464ba79021a991b620092_807x293.png)
例:
```
/**
* @api {get} /user/getUserById/:id
* @apiHeader {String} access-key Users unique access-key.
*/
```
## @apiHeaderExample
请求头部参数示例
```
@apiHeaderExample [{type}] [title]
example
```
![](https://img.kancloud.cn/cc/13/cc13a0ab133e76e70eb90fd3acfce17c_807x184.png)
例:
```
/**
* @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
```
![](https://img.kancloud.cn/c0/41/c0416eb5788f15c6d269f8db4b82e670_801x179.png)
## @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]
```
![](https://img.kancloud.cn/60/0b/600b8ebb3b59bc4b6c5a00b3864cbdaf_819x276.png)
例:
```
/**
* @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
```
![](https://img.kancloud.cn/4d/d2/4dd2cf6545e67b25138ecc58fe32ba46_783x170.png)
```
/**
* @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
```
![](https://img.kancloud.cn/46/17/46170f003c60dd58afe4b39f15a12b89_975x643.png)