apiDoc 文档使用指南

安装

1. 安装node.js
2. 安装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定义的描述

更详细的说明请参考官方文档http://apidocjs.com

生成文档

cd到apidoc.json所在路径(即项目根目录)执行如下命令即可

apidoc -i src/ -o apidoc/

执行成功后会生成apidoc文件夹如下图所示

图片

点开apidoc文件夹中index.html会发现已经生成的漂亮的api文档

图片

15人点赞

技术管理

作者：袁志健
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。