apidoc安装及应用

apidoc 是一款支持多编程语言Restful API的文档自动生成工具，本文从安装到生成APP接口API文档进行讲解。

参考资料

官方教程： http://apidocjs.com/
中文教程：https://blog.csdn.net/qq_34627459/article/details/71810318
NodeJs下载：http://nodejs.cn/download/

安装NodeJS

apiDoc依赖nodejs，因此需要先搭建nodejs环境后，再通过命令行模式安装apiDoc

1. 下载NodeJs并配置环境变量，下载页面选择系统对应版本下载即可，此处选择win64位系统zip版
2. 配置环境变量，同配置jdk环境变量一致，win下将nodejs根目录加入到path环境变量中即可，安装完成后，执行命令确认是否安装成功。

npm -v

安装成功后，出现下图所示

image

安装apiDoc

上一步骤已将nodejs环境安装配置完成，接下来只需要安装apiDoc即可，执行下述命令进行安装

npm install apidoc -g

nodejs 版本

由于本机之前已经安装过了，所以提示如图更新信息，执行以下命令校验是否安装成功

apidoc -v

image

出现上图所示信息，则apiDoc已经安装成功了。

image.png

集成到项目中

1.进入项目根目录下，创建apidoc.json文件，内容如下

{
  "name": "API名称",
  "version": "API主版本号，仅支持3位数字版本号，如：0.0.1",
  "description": "API描述信息",
  "title": "浏览器标题",
  "url": "可选，接口地址，如：http://p2p-12.test13.wangdai.me/sp2p_srd",
  "sampleUrl": "可选，接口调用示例地址，如增加此项，则页面会增加可发送请求示例的操作项",
  "header": {
    "title": "可选，头部标题",
    "filename": "可选，头部文件路径，只支持.md文件"
  },
  "footer": {
    "title": "可选，底部描述",
    "filename": "可选，底部文件路径，只支持.md文件"
  },
  "template": {
    "withCompare": true, //是否允许版本之间进行比较
    "withGenerator": true//是否允许生成多个版本
  }
}

2.进入项目根目录下，创建apidoc.js文件，按需创建版本库文件，如:v9.4.x.js文件。

apidoc.js文件主要用于定义一些公共文档，接口中使用@apiUse引用。
文件不限制于js文件，也可以为java文件，只要apidoc支持的文件类型皆可以正常解析。
版本库文件用于分离apidoc.js文件，存储历史版本变更文档数据，接口变动前将方法上的apidoc文档复制到对应版本库文件中，新文档更新@apiVersion即可，便于后续版本对比。
版本库命名规范：以v+版本号开头，v9.4.0.0-v9.4.9.9均合成到v9.4.x.js文件中，避免创建过多文件。

apidoc.js 文件

/**
 * APP API接口文档
 *
 * 文档基于apidoc编写，官网地址：http://apidocjs.com
 *
 *  如遇版本变更，请将历史api注释复制到原对应版本js文件中，如登录接口升级到4.1.1，则将原4.1.0注释文档复制到v9.4.x.js文件中
 *
 * @author FanWeiJie
 * @date 2018-07-21 08:34:55
 */

/**
 * @apiDefine apidoc
 * @apiParam {int{2,3}} deviceType 请求设备的类型：<code>{1:安卓，2:IOS}</code>
 *
 * @apiSuccess {int{-999-999}} result.code 响应代码<code>{1:成功，<0:失败}</code>
 * @apiSuccess {String} result.msg 响应描述
 */

v9.4.x.js 文件

/**
 * v9.4.x 版本变更更新文档存档
 *
 * @author FanWeiJie
 * @date 2018-07-21 08:34:55
 */
 
/**
* @api {POST} /userLogin 用户登录
* @apiDescription 根据用户名、手机号码+密码登录
* @apiVersion 4.1.0
* @apiName userLogin
* @apiGroup user
*
* @apiUse apidoc
* 
* @apiParam {String{13000000000-19900000000}} mobile 手机号码或者用户名
* @apiParam {String} password 登录密码，使用3DES加密上送
* @apiParam {int{1,2}} [userType=1] 用户类型，<code>{1：个人，2：企业}</code>
*/

3.shift+右键打开命令行窗口，执行下述命令，会创建apidoc目录并将api文档文件生成到该目录下，首次执行该命令，apidoc目录下可能为空，因为代码中尚未编写apidoc文档。

apidoc -i 指定需要生成文档源码根目录 -o 指定输出目录

image

编写apidoc文档

在Controller或者接口定义类中编写apidoc文档，文档中的注解参照官网说明

/**
* @api {POST} /userLogin [123]用户登录
* @apiDescription 根据用户名、手机号码+密码登录
* @apiVersion 4.1.0
* @apiName userLogin
* @apiGroup user
*
* @apiUse apidoc
* 
* @apiParam {String{13000000000-19900000000}} mobile 手机号码或者用户名
* @apiParam {String} password 登录密码，使用3DES加密上送
* @apiParam {int{1,2}} [userType=1] 用户类型，<code>{1：个人，2：企业}</code>
*/
public static String logining(Map<String, String> parameters, Map<String, Object> application) {
    //省略代码
}

<a name="c11fea6c"></a>

apidoc注解

这里只介绍几个常用的，完整更详细的可参考官方文案及示例

@api

@api {method} path [title]

# method 请求方式：GET/POST/PUT/DELETE等
# path 请求路径及参数，不包含域名及contextPath，如：/user/:id
# [title] 可选，接口描述

必须

定义接口的请求方式、请求路径、接口名称、接口描述。

示例

// 获取用户可用红包列表
@api {POST} /redpacketIndex [611]红包列表

规范

定义为何种请求方式没有关系，APP接口调用地址并非此地址，接口名称前统一添加[接口号]便于排序及通过接口号查找。

@apiDescription

@apiDefine name [title] [description]

可选

针对接口的简单描述信息。

示例

//获取用户可用红包列表
@apiDescription 账户中心 > 我的红包 > 红包列表

@apiName

@apiName name

# name 接口名称

定义接口名称，保证全局唯一。

必须

示例

//获取用户可用红包列表
@apiName redpacketIndex

规范

跟@api中的path变量保持一致。

@apiVersion

@apiVersion version

# 接口版本号，可与apidoc.json文件中的主版本号不一致，需纯数字

必须

定义接口的版本号

示例

@apiVersion 4.1.0

规范

apidoc仅支持3位纯数字版本号，因此去掉晓风系统版本号，从需求版本号开始定义即可，如4.1.0。

@apiGroup

@apiGroup name

必须

接口分组，按需分组，可按照app底部菜单，或按照user等类型分组，接口分组后，生成的文档将会把同一个组的接口汇总一块，效果图如下。

image

示例

@apiGroup reward

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

[(group)] 分组，可选，建议弃用
[{type}] 参数类型：String/Number/Date/Boolean等。
[field=defaultValue] 默认值，设置了默认值则代表该参数为可选参数。
[description] 参数描述信息

必须

定义接口请求参数类型、字段、字段规则、默认值、参数描述。

# 定义一个String类型的参数
@apiParam {String} userId 用户ID

# 定义一个int类型，取值范围在[1-2]之间的值，默认值为1
@apiParam {int{1,2}} [redType=1] 红包类型：<code>{1:奖励红包，2:投资红包}</code>

# 定义一个int类型，取值范围在[000-999]之间的值，默认为1
@apiParam {int{000-999}} [currPage=1] 当前页码

# 定义一个int类型，取值范围在[000-999]之间的值，默认为8
@apiParam {int{000-999}} [pageSize=8] 页记录数

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]

# [(group)] 分组，可选，建议弃用
# [{type}] 参数类型：String/Number/Date/Boolean等
# field 参数名称
# [description] 参数描述

必须

定义接口请求成功后返回客户端的参数。

示例

# 定义个double的返回参数
@apiSuccess {double} useBalance 可兑换佣金

# 定义一个List类型的返回参数
@apiSuccess {List} cpsUsers 推广会员列表

@apiDefine & @apiUse

@apiDefine name [title] [description]
# name 名称
# [title] 标题，可选
# [desciption] 描述，可选

@apiUse name
# name @apiDefine定义的name属性值

可选

定义一个公共文档，提供接口文档引用，需配合@apiUse使用。

示例

// 定义公共文档
/**
 * @apiDefine apidoc
 * @apiParam {int{2,3}} deviceType 请求设备的类型：<code>{2:安卓，3:IOS}</code>
 *
 * @apiSuccess {int{-999-999}} result.code 响应代码<code>{1:成功，<0:失败}</code>
 * @apiSuccess {String} result.msg 响应描述
 */

// 引用公共文档
@apiUse apidoc