日常工作记录——JAVA中APIDOC的应用
一、APIDOC是什么？
简单通俗点说，apidoc是一款自动生成API接口文档的工具。它支持多种语言的接口文档生成，如C#、Java、JavaScript、PHP、Python等，详情可参考官方文档说明。java代码中可以通过注解来实现apidoc。
二、APIDOC安装
1.因为apidoc依赖于node.js，所以首先要安装node.js
2. 安装apidoc
cmd打开运行命令框，输入命令npm install apidoc -g即可安装。
使用命令apidoc -h可验证是否安装成功。
三、APIDOC使用
1. 配置apidoc.json
在项目中创建apidoc.json文件，位置建议在项目根目录(src目录平级)，也可自选。
apidoc.json内容示例如下：
1 { 2 "name": "项目名称", 3 "version": "项目版本", 4 "description": "项目描述", 5 "title": "浏览器标题", 6 "url" : "api路径前缀，会自动拼接到@api 路径前，可以设置为空串" 7 }
具体参数名配置及含义可参考官方文档
2. 接口增加apidoc注解
具体参数名配置及含义可参考官方文档
3. 生成接口文档
cmd打开运行命令框，cd到apidoc.json目录下，使用apidoc -i src/ -o apidoc/生成HTML格式接口文档
指令参数详情列表：
| 参数 | 描述 |
| -h, --help | 查看帮助文档 |
| -f --file-filters |
指定读取文件的文件名过滤正则表达式(可指定多个)例如: apidoc -f “.*\.js"−f".∗.ts " -f ".*\\.ts"−f".∗.ts” 意为只读取后缀名为js和ts的文件默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue |
| -e --exclude-filters | 指定不读取的文件名过滤正则表达式(可指定多个)例如:apidoc -e “.*\.js$” 意为不读取后缀名为js的文件默认:’’ |
| -i, --input | 指定读取源文件的目录例如：apidoc -i myapp/ 意为读取myapp/目录下面的源文件默认值:./ |
| -o, --output | 指定输出文档的目录例如：apidoc -o doc/ 意为输出文档到doc目录下默认值:./doc/ |
| -t, --template | 指定输出的模板文件例如:apidoc -t mytemplate/默认:path.join(__dirname, ‘…/template/’)(使用默认模板) |
| -c, --config | 指定包含配置文件(apidoc.json)的目录例如:apidoc -c config/默认:./ |
| -p, --private | 输出的文档中是否包含私有api例如:apidoc -p true 默认:false |
| -v, --verbose | 是否输出详细的debug信息例如:apidoc -v true默认:false |
