php-Api接⼝写法规范和要求
前⾔
说明
是⼀个API⽂档⽣成⼯具, apidoc可以根据代码注释⽣成web api⽂档, apidoc从注释⽣成静态html⽹页⽂档，不仅⽀持项⽬版本号，还⽀持api版本号
安装
A). 系统需要安装nodejs(略)
B). 安装apidoc
# 有些系统需要sudo 权限来安装
$ npm install apidoc -g复制代码
C). 执⾏⽣成
# 这个⽂档的⽣成规则是
# apidoc
# -i code_dir
# -o output_dir
phpjson格式化输出$ apidoc -i myapp/ -o apidoc/
# 对于项⽬中我们使⽤ laravel artisan 封装了⼀个函数
# ⽣成 api doc ⽂档
$ php artisan lemon:doc apidoc复制代码
注意: 分组名不⽀持中⽂，可修改
使⽤
A) ⽣成⽂档
$ apidoc -i myapp/ -o doc/api [-c ./] -f ".*\.js$"复制代码
-
i 表⽰输⼊，后⾯是⽂件夹路径
-o 表⽰输出，后⾯是⽂件夹路径
默认会带上-c，在当前路径下寻配置⽂件 apidoc.json，如果不到则会在package.json中寻 "apidoc": { }
-f 为⽂件过滤，后⾯是正则表达式，⽰例为只选着js⽂件
-e 的选项，表⽰要排除的⽂件/⽂件夹，也是使⽤正则表达式
B) 项⽬配置
{
"name" : "项⽬名",
"version": "1.0.0",
"title": "mysails-浏览器标题",
"description": "description"
}复制代码
我们的配置存放在根⽬录 package.json ⽂件中.
参数说明和⽰例
apidoc ⽀持如下关键字：(下⾯ [ ] 中括号中表⽰是可选写的内容，使⽤时不⽤加 [ ] 中括号。)
@api {method} path [title]
只有使⽤@api标注的注释块才会在解析之后⽣成⽂档，title会被解析为导航菜单(@apiGroup)下的⼩菜单
method可以有空格，如{POST GET}
@apiGroup name
分组名称，被解析为导航栏菜单
@apiName name
接⼝名称，在同⼀个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后⾯@api会覆盖前⾯定义的@api
@apiDescription text
接⼝描述，⽀持html语法
@apiParam [(group)] [{type}] [field=defaultValue] [description]
详细介绍见: apidocjs/#param-api-param
@apiVersion verison
接⼝版本，major.minor.patch的形式
@apiIgnore [hint]
apidoc会忽略使⽤@apiIgnore标注的接⼝，hint为描述
@apiSampleRequest url
接⼝测试地址以供测试，发送请求时，@api method必须为POST/GET等其中⼀种
@apiDefine name [title] [description]
定义⼀个注释块(不包含@api)，配合@apiUse使⽤可以引⼊注释块
在@apiDefine内部不可以使⽤@apiUse
@apiUse name
引⼊⼀个@apiDefine的注释块
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
⽤法基本类似，分别描述请求参数、头部，响应错误和成功
group表⽰参数的分组，type表⽰类型(不能有空格)，⼊参可以定义默认值(不能有空格)，field上使⽤[]中扩号表⽰该参数是可选参数
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
⽤法完全⼀致，但是type表⽰的是example的语⾔类型
example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使⽤列模式快速对代码添加*号)复制代码
写法规范
参数对齐
/**
* @api {get} /api_prefix/check_verification [O]验证验证码
* @apiVersion 1.0.0
* @apiName HomeCheckVerification
* @apiGroup Home
* @apiParam {String} mobile ⼿机号
* @apiParam {String} captcha 验证码
*/
public function checkVerification(){}复制代码
apiName命名规范
apiName 的命名规范是 apiGroup + functionName;
apiName 的写法规范是 ⾸字母⼤写的驼峰模式
例如上⾯的命名规范是
apiGroup : Home
apiName : HomeCheckVerification复制代码
返回值约定
数字类型, 需要转换成int 类型(返回的json 串中不需要有引号包裹)⽂字类型的, 需要转换成 string 类型
返回值中不允许存在 null
返回值对齐
返回的类型值, 参数值, 说明必须对齐
返回的参数值和真正返回的内容值必须填写完整
/**
* @api {get} /api_prefix/version [O]检测新版本(Android)
* @apiVersion 1.0.0
* @apiName HomeVersion
* @apiGroup Home
* @apiParam {String} version 版本号
* @apiSuccess {String} download_url 下载地址
* @apiSuccess {String} description 描述
* @apiSuccess {String} version 版本
* @apiSuccessExample data:
* {
* "download_url": "http:\/\/domain\/1.1.1.apk",
* "description": "修改bug若⼲, 增加⽀付功能",
* "version": "1.1.1"
* }
*/
public function version()复制代码
路由定义
api 路由⽂件存放在 app/Http/Routes/ ⽂件夹下
Routes/
api_dailian.php
api_up.php
...复制代码
使⽤的PHP组件
系统使⽤ dinggo 作为 api的封装组件
其他说明
A). 接⼝命名
lists => 列表
create => 创建
edit => 编辑
delete => 删除复制代码
B). 参数命名
例如 A下的传递参数, 我们应当使⽤ title ⽽不能使⽤
C). 路由命名
路由的名称和坐在分组还有函数名进⾏匹配, 使⽤蛇形写法
/**
* @api {get} /dailian/bank/lists [O][B]银⾏账户列表
* @apiVersion 1.0.0
* @apiName UserBankList
* @apiGroup User
* @apiSuccess {String} id 账号ID
* @apiSuccess {String} bank_account 账号信息
* @apiSuccess {String} bank_true_name 真实姓名
* @apiSuccess {String} bank_type 账号类型 : ⽀付宝
* @apiSuccess {String} note 备注
* @apiSuccessExample 成功返回:
* [
* {
* "id": 2,
* "bank_account": "123123123",
* "bank_true_name": "⼆狗",
* "bank_type": "⽀付宝",
* "note": ""
* }
* ]
*/
public function lists()复制代码
这⾥的命名是 api_dailian.bank_lists
D). ⾃营的接⼝⽆特殊返回不需要填写说明
E). 接⼝中只能返回有意义的数据, 对app⽆⽤的数据不得返回
F). 列表为空也需要返回分页
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论