使用apidoc自动生成rest风格api接口文档

1 先下载安装nodejs,下载地址:

点击打开链接

2 安装apidoc,命令行执行:

npm install apidoc -g

安装完成后执行:

apidoc --help

检验一下是否安装成功。

3 在java文件的方法上加注释:

/**
	 * @api {get} /policies 获取政策列表
	 * @apiGroup service
	 * @apiVersion 1.0.0
	 * @apiHeader {String} Content-Type application/json.
	 * @apiHeader {String} Client-Type WeChat,IOS,Android.
	 * @apiHeader {String} Authentic-Token UserToken.
	 *
	 * @apiParam {int} policyTypeId 政策类型ID
	 * @apiParam {int} regionId 地区ID
	 * @apiParam {int} pageIndex 分页起点
	 * @apiParam {int} pageSize 获取条数
	 *
	 * @apiExample CURL调用示例:
	 * curl -XGET 'http://localhost:8080/geego/policies?policyTypeId=21&regionId=1&pageIndex=0&pageSize=1'
	 *
	 * @apiSuccessExample Success-Response:
	 * HTTP/1.1 200 OK
	 *{
	 * "pageIndex": 0,
	 * "pageNo": 1,
	 * "pageSize": 1,
	 * "result": [
	 * {
	 * "createTime": 1463132231,
	 * "createUser": 1,
	 * "policyId": 1,
	 * "policyTypeId": 21,
	 * "regionId": 1,
	 * "title": "关于发展众创空间推进大众创新创业的指导意见",
	 * "updateTime": 1463132238,
	 * "updateUser": 1
	 * }
	 * ],
	 * "success": 1,
	 * "totalCount": 0
	 * }
	 * @apiErrorStructure Error500
	 */

具体参数参考:

点击打开链接

4 配置apidoc.json、package.json、header.md、footer.md

apidoc.json

{
  "name": "测试API",
  "version": "1.0.0",
  "description": "测试API",
  "title": "测试API",
  "header": {
    "title": "测试API",
    "filename": "header.md"
  },
  "footer": {
    "title": "测试API",
    "filename": "footer.md"
  }
}

package.json

{
  "name": "测试API",
  "version": "1.0.0",
  "description": "",
  "apidoc": {
    "title": "测试API",
    "url" : "http://127.0.0.1:8080/test"
  }
}

header.md

header

footer.md

footer

5 apidoc安装成功后执行生成文档的命令:

需要注意,执行命令的路径需要和上面四个文件再同一路径下。

apidoc -f .java -i ./src/ -o ./src/main/webapp/WEB-INF/doc -t ./src/main/webapp/WEB-INF/doc/template

参数说明:

-f 文件类型

-i 文件输入路径(必选)

- o 输出路径(必选)

- t 使用模板(非必选)

这样文档就生成了,生成的是静态文件。