1.下载安装node.js
下载地址:https://nodejs.org/en/download/
cmd 中使执行node -v命令查看是否安装成功,如果失败,刷新环境变量再尝试,操作如下:
打开cmd 输入
set path=test
输入
echo %path%
输出为test
2.安装apidoc
命令行下,输入npm install apidoc -g,参考官网:http://apidocjs.com/#install 点击打开链接
npm install apidoc -g
安装完毕,可在命令下使用apidoc -h测试是否安装成功
apidoc -h
3.apidoc指令能成功识别,apidoc环境便已经安装好了,这时可在项目中使用,所有的代码基于注释即可。
4.项目根路径下建立apidoc.json文件,配置好基本的文档信息。
{
"name": "API文档",
"version": "1.0.0",
"description": "开发技术接口文档",
"title": "API文档",
"url" : "http://localhost:8080/test",
"sampleUrl":"http://localhost:8080/test"
}
如图:
5.代码接口中使用:
/**
* @api {get} /rest/area/getAreasByCode 行政区域查询
* @apiDescription 根据行政编码获取行政区域,0获取省级行政区域
* @apiName getAreasByCode
* @apiGroup area
* @apiVersion 1.0.0
*
* @apiParam {String} code 行政编码
*
* @apiSampleRequest /rest/area/getAreasByCode
* @apiUse token_msg
* @apiUse success_msg
* @apiSuccess (success 2000) {String} res.id 标识码
* @apiSuccess (success 2000) {String} res.name 行政地区名称
* @apiSuccess (success 2000) {String} res.code 行政编码
* @apiSuccess (success 2000) {String} res.prevCode 上级行政编码
* @apiSuccess (success 2000) {String} res.allName 全称
*
*/
@RequestMapping("/getAreasByCode")
@ResponseBody
public RestResponse getAreasByCode(String code){
return new RestResponse(areaService.findAreaByPrevCode(code));
}
6.创建批处理文件docGenerator.bat
@echo off
call apidoc -i ./ -o ./main/resources/static/doc
pause
7.打开 doc下的index.html即可访问