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，-输出 |
输出目录名。放置生成的文档的位置。
|
| -t，-模板 | 使用模板输出文件。您可以创建和使用自己的模板。 例： apidoc -t mytemplate/ |
6.访问接口文档。
