首发于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