apiDoc使用指南

apiDoc使用指南：

安装：
1: 需要先安装node.js(安装node.js请浏览相关博客)
2: node.js安装完成后使用命令:
npm install apidoc -g

---

配置：

在你的项目根路径下新建apidoc.json文件,该文件描述了项目对外提供接口的概要信息如名称,版本,描述文档打开时浏览器显示标题和接口缺省访问地址.

---

使用样例：

/**
 *
 * @apiDefine RkNotFoundException
 *
 * @apiError RkNotFoundException 找不到相关数据
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": {
 *           "code": 404,
 *           "msg": "",
 *           "path" ""
 *       }
 *     }
 *
 */

/**
 *
 * @api {get} /v3.1/ues/:sn/rt-info 获取设备上报实时信息
 * @apiVersion 3.1.0
 * @apiName GetUeRealTimeInfo
 * @apiGroup UE
 *
 * @apiHeader {String} Authorization 用户授权token
 * @apiHeader {String} firm 厂商编码
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Authorization": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOjM2NzgsImF1ZGllbmNlIjoid2ViIiwib3BlbkFJZCI6MTM2NywiY3JlYXRlZCI6MTUzMzg3OTM2ODA0Nywicm9sZXMiOiJVU0VSIiwiZXhwIjoxNTM0NDg0MTY4fQ.Gl5L-NpuwhjuPXFuhPax8ak5c64skjDTCBC64N_QdKQ2VT-zZeceuzXB9TqaYJuhkwNYEhrV3pUx1zhMWG7Org",
 *       "firm": "cnE="
 *     }
 *
 * @apiParam {String} sn 设备序列号
 *
 * @apiSuccess {String} sn 设备序列号
 * @apiSuccess {Number} status 设备状态
 * @apiSuccess {Number} soc 电池电量百分比
 * @apiSuccess {Number} voltage 电池电压
 * @apiSuccess {Number} current 电池电流
 * @apiSuccess {Number} temperature 电池温度
 * @apiSuccess {String} reportTime 上报时间(yyyy-MM-dd HH:mm:ss)
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "sn": "P000000000",
 *       "status": 0,
 *       "soc": 80,
 *       "voltage": 60.0,
 *       "current": 10.0,
 *       "temperature": null,
 *       "reportTime": "2018-08-13 18:11:00"
 *     }
 *
 * @apiUse RkNotFoundException
 *
 */
@RequestMapping(value = "/{sn}/rt-info", method = RequestMethod.GET)
public UeRealTimeInfo getUeRealTimeInfo(@RequestHeader(Constants.HEADER_LOGIN_USER_KEY) long userId, @PathVariable("sn") String sn) {

    return ueService.getRealTimeInfo(sn);
}

样式解读：

@api ( @api {method} path [title] ) HTTP接口调用方法,路径及名称

@apiVersion ( @apiVersion version ) api版本号

@apiName (@apiName name) api名称

@apiGroup (@apiGroup name) api分组

@apiHeader (@apiHeader [(group)] [{type}] [field=defaultValue] [description]) 请求头参数

@apiParam (@apiParam [(group)] [{type}] [field=defaultValue] [description]) 请求参数

@apiSuccess (@apiSuccess [(group)] [{type}] field [description]) 返回数据描述

@apiSuccessExample( @apiSuccessExample [{type}] [title] example ) 接口成功返回样例

@apiError @apiError [(group)] [{type}] field [description] 接口失败描述

@apiErrorExample (@apiErrorExample [{type}] [title] example ) 接口失败返回样例

@apiDefine (@apiDefine name [title] [description] ) 类似于宏定义,可以被引用

@apiUse ( @apiUse name ) 使用@apiDefine定义的描述

生成文档：

cd到apidoc.json所在路径(即项目根目录)执行命令:
apidoc -i src/ -o apidoc/