apiDoc 使用指南

短命女 2023-07-13 12:17 14阅读 0赞

# 安装 #

1.  [安装node.js][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"
    }

# 使用样例 #

/**
     *
     * @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][http_apidocjs.com]

# 生成文档 #

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

apidoc -i src/ -o apidoc/

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

![format_png][]

图片

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

![format_png 1][]

[node.js]: https://nodejs.org/zh-cn/
[apidoc.json]: http://apidocjs.com/source/example_full/apidoc.json
[http_apidocjs.com]: http://apidocjs.com
[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly91cGxvYWQtaW1hZ2VzLmppYW5zaHUuaW8vdXBsb2FkX2ltYWdlcy8xNTg2Mjg3LWZiMWNmYmJmMjA3OWRkZWEucG5nIXRodW1ibmFpbD9pbWFnZU1vZ3IyL2F1dG8tb3JpZW50L3N0cmlwfGltYWdlVmlldzIvMi93LzMxNS9mb3JtYXQvd2VicA?x-oss-process=image/format,png
[format_png 1]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly91cGxvYWQtaW1hZ2VzLmppYW5zaHUuaW8vdXBsb2FkX2ltYWdlcy8xNTg2Mjg3LTA2NDU3MDIxMTQ5OWVhOWEucG5nIXRodW1ibmFpbD9pbWFnZU1vZ3IyL2F1dG8tb3JpZW50L3N0cmlwfGltYWdlVmlldzIvMi93LzEyMDAvZm9ybWF0L3dlYnA?x-oss-process=image/format,png