最近公司项目，测试需要我们提供一个接口文档，之前是写在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这一行之上的注释。通常是全局作用的，此类注释能且仅能出现在此处。目前此类注释只有一个
方法注释
即应该放在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": "[email protected]",
* "gender": "1",
* "mobile": "xxxxxxx",
* "name": "测试1",
* "userid": "fenghaiting"
* },
* "uidprofile": { // 点赞人信息
* "avatar": "http://shp.qpic.cn/bizmp/9Qe6l7LKo9mk50V8VSNiamg0h6ibtLicBAosek11EcDyjEXQCkOlvXaiaQ/",
* "email": "[email protected]",
* "gender": "1",
* "mobile": "xxxxxxxx",
* "name": "测试",
* "userid": "fengxingchao"
* }
* }
* ]
* },
* "status": 200,
* "message": "ok"
* }
*/