API文档、apiDoc、部分使用、指南、安装、配置

布满荆棘的人生 2022-12-28 04:16 228阅读 0赞

> **本文主要参考**
> 
>  
> 
>  *  [ApiDoc官方文档][ApiDoc]

# 安装 #

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文件夹如下图所示**

**![da542dfe9c6df7ee8160522162d186fe.png][]**

--------------------

### **其他需求请前往[apiDoc通过源代码中的API注释创建文档（中文版）][apiDoc_API]  或 [ApiDoc官方文档][ApiDoc] 了解** ###

[ApiDoc]: https://link.jianshu.com/?t=http%3A%2F%2Fapidocjs.com%2F
[node.js]: https://nodejs.org/zh-cn/
[apidoc.json]: http://apidocjs.com/source/example_full/apidoc.json
[http_apidocjs.com]: http://apidocjs.com/
[da542dfe9c6df7ee8160522162d186fe.png]: /images/20221120/aafeabcb7c3449099e81bb8fe1e588de.png
[apiDoc_API]: https://blog.csdn.net/qq_41570658/article/details/111173602