apiDoc 文档使用指南
安装
安装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" }复制代码
最后生成项目根目录下,上一级
apidoc -i otc-audit-end/application -o otc-audit-end/public
使用样例
/** * * @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定义的描述
更详细的说明请参考官方文档apidocjs.com
生成文档
cd到apidoc.json所在路径(即项目根目录)执行如下命令即可
apidoc -i src/ -o apidoc/复制代码
执行成功后会生成apidoc文件夹如下图所示
图片
点开apidoc文件夹中index.html会发现已经生成的漂亮的api文档
作者:袁志健
链接:https://juejin.cn/post/7022833170282184741