使用apiDoc书写API文档规范
2018-01-19 本文已影响35人
fxm5547
详细阅读apiDoc官方文档
- 详细阅读官方文档:http://apidocjs.com
项目中apiDoc文件结构
-
整体结构
图片 -
图片apidoc.json
-
common.php
- 公共部分定义-权限(apiPermission)
-
定义
图片 -
使用
图片
-
- 公共部分定义-状态码分组(apiSuccess、apiError)
-
定义
图片 -
使用
图片
图片
-
- 公共部分定义-错误响应(apiError、apiErrorExample)
-
定义
图片 -
使用
图片
-
- 公共部分定义-权限(apiPermission)
-
define.php
- 公共部分定义-api分组
-
定义
图片 -
使用
图片
接口具体apidoc定义
-
接口最新定义在代码实现处,历史版本定义在apidoc/history.php中。
-
接口定义完整示例:
图片 -
@apiVersion
-
目前只用到major和minor,patch始终为0。
-
@apiName
- 从
@api
定义转换而来:
如@api
为:@api {put} /user/babies/:baby_id 修改宝宝信息
,
则@apiName
为:@apiName put/user/babies/:baby_id
,
则解析后的ID为;put_user_babies__baby_id
(用于apidoc.json的order接口排序)。
- 从
-
@apiGroup
- 接口分组,定义在
apidoc/define.php
,如@apiGroup babyGroup
。
- 接口分组,定义在
-
@apiPermission
- 接口权限,定义在
apidoc/common.php
,权限分为:-
none
:无需任何授权; -
token
:需要用户登录授权,可通过header Authorization
和Cookie HBSID
传递; -
admintoken
:需要管理员登录授权,可通过header Authorization
和Cookie HBCPSID
传递; -
token || admintoken
:用户登录授权或管理员登录授权都可以;
图片 -
sign
:需要签名,一般用于服务端相互调用,详见 API HMAC-SHA1签名。
-
- 接口权限,定义在
-
@apiDescription
- 尽可能详细说明接口的用途及相关逻辑,如
@apiDescription 使用手机号找回密码的第一步,调用该接口先验证用户输入的手机号是否已经绑定某个帐号,未绑定给出提示,已经绑定则发送验证码、重置密码
。
- 尽可能详细说明接口的用途及相关逻辑,如
-
@apiParam
- 准确定义数据类型;
- 准确定义取值范围,如
{String{1..32}}
、{String{YYYY-mm-dd}}
、{String="0","1"}
; - 准确定义是否是可选参数,可选参数带
[]
,如@apiParam {String} [stage]
;
-
@apiError
- 公共错误,直接使用
apidoc/common.php
中定义的错误,如@apiUse InvalidToken
; -
NotFound
和ValidationError
不允许使用公共定义错误(即不可使用@apiUse
),需要准确定义具体错误,如:
图片
- 公共错误,直接使用
-
@apiSampleRequest
- GET接口:不写,默认使用
apidoc.json
的sampleUrl
自动组装请求地址 - 其他接口:
@apiSampleRequest off
,我们用Postman
- GET接口:不写,默认使用
接口分组
- 一般按功能模块分组,一个分组对应一个或多个php文件,每个php文件只对应一个分组;
- 所有权限为
admintoken
的接口(不包括权限为token || admintoken
的接口),放在该接口模块的管理中心接口分组,admin.php
文件中; - 所有权限为
sign
的接口(短信模块除外),放在该接口模块的内部服务接口分组,internal.php
文件中;
接口版本管理
-
同一个大版本下,只有当你的接口变更会影响到调用者时,才需要升级minor版本(如果被修改的版本还没有调用者,自然无需升级版本),如从1.0.0升至1.1.0。
-
升级版本时,需要将旧的apidoc注释拷贝至
图片apidoc/history.php
,并升级apiVersion
-
升级接口大版本时,拷贝旧版本文件目录作为新版本并升级接口版本(如拷贝v1,重命名为v2,修改新版本中所有接口为
2.0.0
版本)。 -
调用者在查看文档时,通过版本比较,可以轻易知晓新版本做了哪些变更。
图片
图片 -
过期的接口,标记
@apiDeprecated
,说明应该使用哪些接口替代:-
在过期接口apidoc注释前增加:
图片 -
文档显示:
图片
-
文档生成
-
DEVQA服务器配置了定时任务(
图片crontab -l
查看),每隔1分钟重新生成文档。
-
新建接口模块时,
- 需要修改定时任务
crontab -e
; - 在apidoc模板中新增导航
vim /usr/lib/node_modules/apidoc/template/index.html
;
图片
- 需要修改定时任务
api测试注意要点
- 是否严格遵循本规范定义接口;
- 错误处理周全,不遗漏任何的错误,错误的message必须简洁明了并给予指引,如“开团时间为1-5天,请重新输入”;
- 接口权限控制是否OK,是否存在安全隐患;
- 接口文档和实现是否完全一致;
-请求参数的名称、类型、是否可选、描述都必须准确和见名知意; - 返回参数的名称、类型、描述都必须准确详尽。