使用apiDoc书写API文档规范

首发于fxm5547的博客

详细阅读apiDoc官方文档

• 详细阅读官方文档：http://apidocjs.com

项目中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 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

接口分组

• 一般按功能模块分组，一个分组对应一个或多个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