日常工作记录——JAVA中APIDOC的应用

Posted 2021-12-20 ntfblogs

一、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