apiDoc定义规范

使用apiDoc书写API文档规范

Nov 8, 2017

详细阅读apiDoc官方文档

项目中apiDoc文件结构

  • 整体结构 图片

  • apidoc.json 图片

  • common.php
    • 公共部分定义-权限(apiPermission)
      • 定义 图片
      • 使用 图片
    • 公共部分定义-状态码分组(apiSuccess、apiError)
      • 定义 图片
      • 使用 图片 图片
    • 公共部分定义-错误响应(apiError、apiErrorExample)
      • 定义 图片
      • 使用 图片
  • 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 AuthorizationCookie HBSID传递;
      • admintoken:需要管理员登录授权,可通过header AuthorizationCookie 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
    • NotFoundValidationError不允许使用公共定义错误(即不可使用@apiUse),需要准确定义具体错误,如: 图片
  • @apiSampleRequest
    • GET接口:不写,默认使用apidoc.jsonsampleUrl自动组装请求地址
    • 其他接口:@apiSampleRequest off,我们用Postman

接口分组

  • 一般按功能模块分组,一个分组对应一个或多个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,是否存在安全隐患;
  • 接口文档和实现是否完全一致; -请求参数的名称、类型、是否可选、描述都必须准确和见名知意;
  • 返回参数的名称、类型、描述都必须准确详尽。

修改后的多模块模板

点击下载apidoc-template.zip