apiDoc详解api接⼝⽂档⽣成
PHP使⽤apiDoc api接⼝⽂档
安装apidoc
通过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地址"
}
如果你的项⽬中使⽤了package.json⽂件(例如:node.js⼯程)，那么你可以将apidoc.json⽂件中的所有配置信息放到package.json⽂件中的apidoc参数中：
package.json
{
"name":"系统接⼝⽂档",
"version":"0.0.1",
"description":"⽂档总描述",
"apidoc":{
"title":"apidoc浏览器⾃定义标题",
"url":"⽂档url地址"
}
}
apidoc.json配置项
参数描述
name⼯程名称如果apidoc.json⽂件中没有配置该参数，apidoc会尝试从pakcage.json⽂件中读取
version版本如果apidoc.json⽂件中没有配置该参数，apidoc会尝试从pakcage.json⽂件中读取
description⼯程描述如果apidoc.json⽂件中没有配置该参数，apidoc会尝试从pakcage.json⽂件中读取title浏览器标题
url api路径前缀例如:
sampleUrl如果设置了该参数，那么在⽂档中便可以看到⽤于测试接⼝的⼀个表单(详情可以查看参数@apiSampleReques)
header.title页眉导航标题
header.filename页眉⽂件名(markdown)
参数描述
footer.title页脚导航标题
footer.filename页脚⽂件名(markdown)
order接⼝名称或接⼝组名称的排序列表如果未定义，那么所有名称会⾃动排序"order": [ "Error", "Define", "PostTitleAndError", PostError"] apidoc注释参数
@api
【必填字段】否则，apidoc会忽略该条注释
@api {method} path [title]
参数列表:
参数必填描述
method yes请求类型:DELETE, GET, POST, PUT, ...更多
path yes请求路径
title no接⼝标题
例：
/**
* @api {get} /user/getUserById/:id 获取⽤户数据 - 根据id
*/
@apiErrorExample
接⼝错误返回⽰例(格式化输出)
@apiErrorExample [{type}] [title]
example
参数列表:
参数必填描述
type no响应类型
title no⽰例标题
example yes⽰例详情(兼容多⾏)
例：
/**
*@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]
参数列表:
参数必填描述
name yes注释模块名称(唯⼀)，不同@apiVersion可以定义相同名称的注释模块title no注释模块标题
description no注释模块详细描述(详细描述另起⼀⾏，可包含多⾏)
例：
/**
* @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]
参数列表:
参数必填描述
text yes多⾏⽂字描述
例：
/**
* @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]
参数列表:
参数必填描述
text yes多⾏⽂字描述
例：
/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/
@apiError
浏览器json格式化错误返回参数
@apiError [(group)] [{type}] field [description]
参数列表:
参数必填描述
(group)no所有的参数都会通过这个参数进⾏分组，如果未设置，默认值为Error 4xx
{type}no返回类型，例如{Boolean}， {Number}， {String}， {Object}，{String[]}（字符串数组），…
field yes返回id
description no参数描述
例：
/**
* @api {get} /user/getUserById/:id 获取⽤户数据 - 根据id
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
/**
* @apiError (错误分组) {Object} xxx xxxxxxxx
*/
@apiExample
接⼝⽅式请求⽰例
@apiExample [{type}] title
example
参数列表:
参数必填描述
type no请求内容格式
title yes⽰例标题
example yes⽰例详情(兼容多⾏)
例：
/**
* @api {get} /user/getUserById/:id
* @apiExample {curl} Example usage:
* curl -i 127.0.0.1/user/getUserById/1
*/
@apiGroup
定义接⼝所属的接⼝组，虽然接⼝定义⾥不需要这个参数，但是您应该在每个接⼝注释⾥都添加这个参数，因为导出的接⼝⽂档会以接⼝组的形式导航展⽰。
@apiGroup name
参数列表:
参数必填描述
name yes接⼝组名称(⽤于导航，不⽀持中⽂)
例：
/**
* @apiDefine User ⽤户信息
*/
/**
* @api {get} /user/getUserById/:id
* @apiGroup User
*/
@apiParam
接⼝请求体参数
@apiParam [(group)] [{type}] [field=defaultValue] [description]
参数列表:
参数必
填
描述
(group)no所有的参数都会以该参数值进⾏分组(默认Parameter) {type}no返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
{type{size}}no 返回类型，同时定义参数的范围{string{…5}}意为字符串长度不超过5{string{2…5}}意为字符串长度介于25之间
{number{100-999}}意为数值介于100999之间
{type=allowedValues}no 参数可选值{string=“small”}意为字符串仅允许值为"small"{string=“small”,“huge”}意为字符串允许值为"small"、“huge”{number=1,2,3,99}意为数值允许值为1、2、3、99{string {…5}=“small”,"huge"意为字符串最⼤长度为5并
且值允许为:“small”、“huge”
field yes参数名称(定义该请求体参数为必填) [field]yes参数名称(定义该请求体参数为可选) =defaultValue no参数默认值
description no参数描述
例：
发表评论