spring项目集成apidoc快速搭建后台RestFul APi访问文档

1.准备工作:

a.安装node.js

检查是否安装成功nodejs：

node -h

b.安装apidoc

npm install apidoc -g

若npm下载的过慢,可使用淘宝镜像:

cnpm install apidoc -g

检查apidoc是否安装成功:

apidoc -h

 

2.项目内创建apidoc.json文件

在项目根目录下,即src同级目录下创建apidoc.json文件。

 

{
  "name": "XXX项目后台接口API",
  "version": "1.0.0",
  "description": "XXX后台所有接口"
}

文件内容写入项目名称(name),描述(description),版本(version)

3.编写各个接口的api文档

在项目内创建apidoc.java文件,也可以直接写在各个接口方法上以注释的形式，在开发过程中针对各个接口进行单独编写。

当前项目下将所有接口写入apidoc.java文件中.

在src/szsti/下创建apidoc.java文件。

以apidoc的注释语法进行编写每个接口的相关信息:

/**
 * @api {post} https://xxxxx/DataBus/exchange 用户登录
 * @apiVersion 1.0.0
 * @apiGroup User
 *@apiDescription 此接口用于登录获取Token
 * CONSUMER_ID的值必须为后台配置过的参数。
 * @apiParam {String} SERVICE_CODE 接口code
 * @apiParam {String} userId 用户id
 * @apiParam {String} password 密码
 * @apiParam {String} CONSUMER_ID Token分组
 * @apiSuccess {Object} SYS_HEAD 返回码
 * @apiSuccess {Object} BODY  返回数据
 *
 * @apiParamExample {json} Request-Example:
 *   {
 *    "password"     : "xxxxx",
 *    "SERVICE_CODE" : "szsti.proxy.user.FireLogin",
 *    "userId"       : "xxx",
 *    "CONSUMER_ID"  : "RiskWeb"
 *  }
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *    "SYS_HEAD"          : {
 *       "RET"               : [
 *          {
 *             "RET_CODE"          : "000000",
 *             "SERVICE_CODE"      : "szsti.proxy.user.FireLogin",
 *             "RET_MSG"           : "操作成功"
 *          }
 *       ],
 *       "RET_STATUS"        : "S"
 *    },
 *    "BODY"              : {
 *       "imgurl"            : "noheader.jpg",
 *       "USER_ID"           : "1",
 *       "login_Proxy_Token" : "RiskWeb-10e35a16898a44e889f4cb20c70838ec",
 *    }
 * }
 */

4.生成apidoc的访问文件

打开windows下的命令提示符窗口,cd到当前项目根目录下。

执行: apidoc -i ./src -o ./WebContent/apidoc

参数说明:

-i ./src 表示读取src目录下所有的带注释的文件并将注释生成相应的html访问文件。

-o ./WebContent/apidoc 表示将访问文件生成在WebContent文件夹下.

生成的静态文件如下:

5.启动项目进行访问apidoc

由于我是springmvc项目,WebContent下的文件夹可以直接项目名+文件名进行访问。启动项目后,

浏览器输入:http://127.0.0.1/DataBus/apidoc

DataBus为本项目项目名称,apidoc是项目开发之后整合入项目内的。

apidoc的基本原理:

  个人理解,不喜勿喷.

 apidoc插件会根据设置的-i 下的参数，扫描文件夹下的所有文件查找出所有带注解的注释语句,并按照规则将这些信息生成相应的静态文件，即可进行显示的api页面文档。并将文件生成在所设置的文件夹下.

更多注解语法,请参考apidoc官网:http://apidocjs.com/#param-api-group