php apidoc文档生成

最近公司项目，测试需要我们提供一个接口文档，之前是写在wiki里面的，需要时刻去更新，但是更新往往会不及时，这就导致了测试和开放之间存在不可调和的矛盾。  于是，便提出了这种借口文档需求。 基于这种情况，经过调研发现， apidoc能够很好的解决这个问题。下面就来讲讲apidoc的安装使用。

apidoc.js 使用说明及其规范

安装说明

为了不污染大家各自开发环境，以下均假设大家在docker环境中使用，这里有安装说明=>Enterprise Linux

第一步 :安装nodejs环境,已有可忽略（请切换为root用户）:

# for Node.js v6 LTS curl –silent –location https://rpm.nodesource.com/setup_6.x | bash – # 当上面的命令执行成功之后，即可安装nodejs. yum install -y nodejs

第二步: 安装apidoc.js

# 全局安装apidoc.js npm install apidoc -g # 如果安装成功，可以执行下面的命令看一下自己的apidoc版本，正常情况下，应该是0.17.5+ npm view apidoc version # apidoc –help 会给出他所支持的参数

语法

apidoc.js 所支持的语法比较简单，所有支持的语法可以参考http://apidocjs.com/文档。大约10分钟即可浏览完毕。

规范

配置规范

apidoc.json配置文件都必须给出，且配置文件目录必须放在与项目相同的config配置文件目录。内容分为俩类:

• 必须包含的条目

• • name 项目名
  • version 版本
  • description 项目描述
  • title 浏览器标题
  • url API请求地址

• 可选条目

• • sampleUrl 如果给了，就可以看到测试API用的输入框(参见注解@apiSampleRequest )
  • header 可以在API文档前引入一个markdown做额外说明(如果指定，该markdown目录建议放在config目录下)
  • footer 可以在API文档后面引入一个markdown做额外说明(如果指定，该markdown目录建议放在config目录下)
  • order API接口的顺序
  • template 制定展示模版的一些配置，比如ajax参数,是否展示生成时间等。

一个最简单的样例(/path/to/config/apidoc.json):

{ “name”: “example”, “version”: “0.1.0”, “description”: “apiDoc basic example”, “title”: “Custom apiDoc browser title”, “url” : “https://api.github.com/v1” }

语法规范

所有apidoc.js注释应放在controller中。即目录为controllers中的文件。注释目前分为俩个大类，一个是关于类的，另一个是关于方法的。

类注释

该注释是指放在class SomeController这一行之上的注释。通常是全局作用的，此类注释能且仅能出现在此处。目前此类注释只有一个

• @apiDefine

方法注释

即应该放在function actionSome这一行之上的注释。此类注释必须出现在此处。对于所有controller里面需要用于路由的方法(即action前缀的方法，均需要注释)。所有API注释必须包含以下信息:

• @api 包含请求方法 请求路径 和请求标题
• @apiName 请求方法名
• @apiGroup 请求所属于组
• @apiSuccessExample 请求成功样例

以下注释是可选的:

• @apiParam 请求参数，如果该API有请求参数，请必须带上此注释，并且可能详细的描述您的参数。必要的时候可以带上@apiParamExample以供学习
• @apiPermission 该接口是否需要授权
• @apiUse 使用@apiDefine 定义出来的东西
• @apiVersion 版本
• @apiHeader 请求头
• @apiDprecated
• @apiSampleRequest 演示如何请求

一个完整的演示如下:

 /**
     * @api {get} microCommunity/Vote/list 点赞列表
     *
     * @apiDescription 获取指定用户的点赞列表或者被点赞列表.
     *
     * @apiName list
     * @apiGroup vote
     *
     * @apiParam {String}  [uid=当前登录用户] 需要查询的用户id.
     * @apiParam {String}  [offset=null] 分页时需要的偏移量，该值会在第一次请求之后返回供客户端使用.
     * @apiParam {Integer} [size=10] 期望分页返回的数据页大小.
     * @apiParam {Enums(String)}  [type=liked] 类型，分为(`liked`:点赞)和(`beliked`:被点赞).
     *
     * @apiSuccessExample Success-Response://这里的JSON可以不用格式化，因为apidoc.js会自动格式化,但是最好格式化放在这里，方便别人看.
     *  {
     *   "data": {
     *    "offset": null, // 返回null则表示没数据了。
     *    "size": 10,
     *    "current_size": 1, // 当前页实际大小.
     *    "data": [
     *      {
     *        "_id": "58fd6895ce1cdd222bb23bc0",
     *        "uid": "fengxingchao",  // 点赞人ID
     *        "target": "fenghaiting", // 被点赞人ID
     *        "action": "like",        // 动作类型，目前仅有like一种,此action对前端无用，无需关心.
     *        "create_time": 1493002389, // 点赞时间.
     *        "update_time": 1493002389,  // 点赞更新时间.
     *        "create_time_fmt": "2017-04-24 10:04:09", // 点赞时间
     *        "update_time_fmt": "2017-04-24 10:04:09", // 点赞更新时间
     *        "message": "你好啊",         // 点赞理由.
     *        "targetprofile": { // 被点赞人信息
     *          "avatar": "http://shp.qpic.cn/bizmp/9Qe6l7LKo9miapKGAM5WOye63YoztzaH1XqEFsDlgRGpbH7DYAtAzmA/",
     *          "email": "fenghaiting@camera360.com",
     *          "gender": "1",
     *          "mobile": "xxxxxxx",
     *          "name": "测试1",
     *          "userid": "fenghaiting"
     *        },
     *        "uidprofile": { // 点赞人信息
     *          "avatar": "http://shp.qpic.cn/bizmp/9Qe6l7LKo9mk50V8VSNiamg0h6ibtLicBAosek11EcDyjEXQCkOlvXaiaQ/",
     *          "email": "fengxingchao@camera360.com",
     *          "gender": "1",
     *          "mobile": "xxxxxxxx",
     *          "name": "测试",
     *          "userid": "fengxingchao"
     *        }
     *      }
     *    ]
     *  },
     *   "status": 200,
     *   "message": "ok"
     * }
     */

Be the First to comment.