安装
- 安装node.js
- 安装apiDoc
npm install apidoc -g
配置
在你的项目根目录下新建apidoc.json文件，该文件描述了项目对外提供接口的概要信息如名称、版本、描述、文档打开时浏览器显示标题和接口缺省访问地址。
apidoc.json
{
"name": "ServiceEbikeAPIs",
"version": "3.1.0",
"description": "车辆服务接口文档",
"title": "ServiceEbikeAPIs",
"url" : "http://cjl3.rokyinfo.net:7190/api-ebike"
}
使用样例
/**
*
* @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定义的描述
更详细的说明请参考官方文档http://apidocjs.com
生成文档
cd到apidoc.json所在路径（即项目根目录）执行如下命令即可
apidoc -i src/ -o apidoc/
执行成功后会生成apidoc文件夹如下图所示
图片
点开apidoc文件夹中index.html会发现已经生成的漂亮的api文档
图片