Spring项目集成apidoc生成api接口文档

一、背景需求

 JavaWeb/spring项目写成的api接口，需要自动生成api文档，甚至需要在线测试接口。考虑实现的方案有swagger，apidoc，spring rest docs。在之后的项目都有一一尝试，最终还是觉得apidoc的方式比较合适，虽然有一些问题（针对在线测试方面），但可以进行定制修复并解决。

二、方案对比

1.现在大家普遍使用的是swagger结合springmvc来生成api接口文档，对比apidoc，swagger有一个明显的劣势，便是返回的响应，无法生成文档描述，即无法描述响应体的数据结构，这对前后端对接，或者是与移动端/其他端对接来说，需要耗费更多的交流成本，沟通成本，即不可能每个接口都通过实际调用后，看返回实体获悉响应参数。针对后端改动响应体这种情况，又会导致新的问题存在。

2.spring rest docs，这是spring体系里提供的一种接口生成框架，基于mockmvc编写单元测试，单元测试通过即可生成可供阅读的接口文档。这种生成方式需要编写详细的测试单元，并且稍微一点出错便导致编译不通过，对于程序的严谨有一定帮助，但又牺牲一些时间，并且最终生成的文档是基于测试用例数据，没有类似swagger和apidoc的在线测试功能。

3.apidoc，通过注释，生成接口文档，不像swagger和spring rest docs嵌入在代码中，仅仅是通过注释而已。缺点是在线测试功能有些问题，不支持文件表单，但这些缺陷都是可以弥补的，可通过再编程，重新定制源码实现，基于handlebars.js。

三、环境准备

1.安装node.js，

官网：https://nodejs.org/en/点击打开链接；windows64位下载地址https://nodejs.org/dist/v8.9.4/node-v8.9.4-x64.msi下载；

Linux 上安装 Node.js

参考地址：https://www.runoob.com/nodejs/nodejs-install-setup.html

直接使用已编译好的包

1.1 Node 官网已经把 linux 下载版本更改为已编译好的版本了，我们可以直接下载解压后使用：

# wget https://nodejs.org/dist/v10.9.0/node-v10.9.0-linux-x64.tar.xz    // 下载
# tar xf  node-v10.9.0-linux-x64.tar.xz       // 解压
# cd node-v10.9.0-linux-x64/                  // 进入解压目录
# ./bin/node -v                               // 执行node命令 查看版本

   v10.9.0

1.2 解压文件的 bin 目录底下包含了 node、npm 等命令，我们可以使用 ln 命令来设置软连接：

ln -s /software/node-v10.9.0-linux-x64/bin/npm   /usr/local/bin/ 
ln -s /software/node-v10.9.0-linux-x64/bin/node   /usr/local/bin/

1.3环境配置

vim /etc/profile

export PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

source  /etc/profile

1.4 再输入npm -v 或者node -v 就能看到版本号啦~

 

2.安装apidoc，

命令行下，输入npm install apidoc -g，参考官网：http://apidocjs.com/#install 点击打开链接

npm install apidoc -g

  2.1 ln 命令来设置apidoc软连接：

ln -s /software/node-v10.9.0-linux-x64/bin/apidoc  /usr/local/bin/

2.2 安装完毕，可在命令下使用apidoc -h测试是否安装成功

apidoc -v

 

四、整合项目使用

1.项目根路径下建立apidoc.json文件，配置好基本的文档信息。

{
  "name": "API文档",
  "version": "1.0.0",
  "description": "开发技术接口文档",
  "title": "API文档",
  "url" : "http://localhost:8080/test",
  "sampleUrl":"http://localhost:8080/test"
}

 2.demo 目录下添加demo.js编写接口文档内容，内容也可写在java接口前面部分

/**
 * @apiDefine A9999DemoInterface 风险预警应急中心
 */


/**
 * @api {GET} /app/api/getNewestDate 1-1 获取最新有数据的日期
 * @apiName getNewestDate
 * @apiGroup A9999DemoInterface
 * @apiDescription 获取最新有图片的日期
 * @apiParam {String} token 比如xxxxxx_grand
 * @apiVersion 0.0.1
 * @apiSuccessExample {JSON} Success-Response:
{
    "code": 0,
    "msg": "success",
    "data": String // 日期
}
*/

/**
 * @api {GET} /app/api/getRadarPicCount 1-2 获取指定日期的三个月内的每日数据次数
 * @apiName getRadarPicCount
 * @apiGroup A9999DemoInterface
 * @apiDescription  获取指定日期的三个月内的每日数据次数
 * @apiParam {String} addtime 当前日期三个月内的数据次数
 * @apiParam {String} token 比如xxxxxx_grand
 * @apiVersion 0.0.1
 * @apiParamExample  {json} Request-Example:
 *     {
          "addtime":"2020-01-18"
       }
 * @apiSuccess (200) {Object} data 返回数据格式见下面json对象及备注
 * @apiSuccessExample {JSON} Success-Response:
{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "addtime":"2020-01-18", //雷达预警时间
            "radarCount": "500112"  //次数
        }, ....
    ]
}
*/

或者如下这种，两种都支持

 3，把项目拷贝到apidoc所在系统的linux目录中

 5，生成apidoc文档，apidoc -i ./ -o ./src/main/webapp/WEB-INF/doc

apidoc -i /software/manualPictrue/ -o /software/apache-tomcat-8.0.53-9100/webapps/apidoc/ 

重要参数：

参数	描述
-f，--file-filters	RegEx-Filter选择要解析的文件（可以使用许多-f）。默认.cs .dart .erl .go .java .js .php .py .rb .ts。 示例（仅解析.js和.ts文件）： apidoc -f ".*\.js$" -f ".*\.ts$"
-i，-输入	输入/源目录名。项目文件的位置。就是需要生成文档的注释文件所在目录，会从内部寻找。 例： apidoc -i myapp/
-o，-输出	输出目录名。放置生成的文档的位置。 例：目录我让他生成在我此台主机的tomcat下面，他生成目录后我就可以直接通过tomcat访问接口文档 apidoc -o /software/apache-tomcat-8.0.53-9100/webapps/apidoc/
-t，-模板	使用模板输出文件。您可以创建和使用自己的模板。 例： apidoc -t mytemplate/

 6.访问接口文档。