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/