如何使用apidoc来自动更新API文档
安装apidoc
使用nodejs来进行安装
npm install apidoc -g
在项目路径下创建apiodc.josn文件
可以参考如下的格式来进行设置
{
"name": "EnergyRiver API",
"version": "1.0.0",
"description": "EnergyRiver API 使用文档",
"title": "EnergyRiver API 使用说明",
"url" : "http://localhost/public/doc/index.html",
"order": [
"Index",
"Get",
"Post",
"Update",
"Delete",
"Overview",
"Comment"
],
"header": {
"title":"GENERAL",
"filename": "src/main/webapp/public/doc/header.md"
}
}
将如上文件保存到apidoc.josn文件
创建文档的header
由于我们一般会api的访问地址,因此我们可以选择把api文档放在webapp下面。header.md是用来作为整个文档页面的头部信息出现的。
在apidoc.json文件中,我们指定了filename=src/main/webapp/public/doc/header.md
方法注释模板
注意:一般为了保证文档格式不被编辑器更改,使用/*
,而不是/**
来开启注释,
但是/*
开启的注释,是不能被识别的,所以,注释必须以/**
开始,编写过程尽量不要使用IDE的格式化功能。
/**
* @api {get} /build/getBuildingInfo 获取所有建筑单元的信息
* @apiName getBuildingInfo
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "code": 200,
* "data": "建筑单元实际数据数组",
* "total": "总共数量"
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": null,
* "total": 0
* }
*/
@RequestMapping(value = "/getBuildingInfo")
@ResponseBody
public Map<String, Object> getBuilingInfo(HttpServletRequest request) throws Exception {
// 从session拿到token,再解密得到userid
Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
// 按照userID来显示该用户登录时显示的建筑
Map<String, Object> map = new HashMap<>();
List<BuildingInfo> buildingInfos;
if (loginInfo != null) {
Long userID = AuthUtil.getUserId(request);
buildingInfos = buildingInfoService.getbuildingInfo(userID);
map.put("code", 200);
map.put("data", buildingInfos);
map.put("total", buildingInfoService.getAllCount());
} else {
map.put("code", 401);
map.put("data", null);
map.put("total", 0);
}
return map;
}
生成文档
可以使用gitbash,在项目根路径下执行
$ apidoc -i src/main/java/ -o src/main/webapp/public/doc/
如果没有报错的话,就可以执行在public/doc中看到生成的文件了。
访问文档
打开public/doc/index.html就可以访问了
定制样式
可以更改public/doc/css/style.css的内容来自定义api页面的样式
附加一个完整的demo
package cn.b507.ssm.controller.Build;
import cn.b507.ssm.po.Build.BuildingInfo;
import cn.b507.ssm.po.Build.BuildingType;
import cn.b507.ssm.service.Build.BuildingInfoService;
import cn.b507.ssm.tool.token.AuthUtil;
import com.alibaba.fastjson.JSONObject;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* <p>
* Title: BuildingInfoController
* </p>
* <p>
* Description:与建筑单元信息相关的业务需求处理controller
* </p>
*
* @version 1.0
* @date 2017-4-17
*/
@Controller
@RequestMapping("/build")
public class BuildingInfoController {
@Autowired
private BuildingInfoService buildingInfoService;
/**
* @api {get} /build/getBuildingInfo 获取所有建筑单元的信息
* @apiName getBuildingInfo
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "code": 200,
* "data": "建筑单元实际数据数组",
* "total": "总共数量"
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": null,
* "total": 0
* }
*/
@RequestMapping(value = "/getBuildingInfo")
@ResponseBody
public Map<String, Object> getBuilingInfo(HttpServletRequest request) throws Exception {
// 从session拿到token,再解密得到userid
Long userID;
if(request.getParameter("userID")!=null)
userID = Long.parseLong(request.getParameter("userID"));
else
userID = AuthUtil.getUserId(request);
Map<String,Object>map = new HashMap<>();
if (userID != null) {
List<BuildingInfo> buildingInfos = buildingInfoService.getbuildingInfo(userID);
map.put("code", 200);
map.put("data", buildingInfos);
map.put("total", buildingInfoService.getAllCount(userID));
} else {
map.put("code", 401);
map.put("data", null);
map.put("total", 0);
}
return map;
}
/**
* @api {get} /build/getBuildingInfoByID 根据建筑id来查询建筑的信息
* @apiName getBuildingInfoByID
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiParam {Number} buildingID 某个建筑单元的id
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "code": 200,
* "data": "建筑单元实际数据数组"
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": null
* }
*/
@RequestMapping(value = "/getBuildingInfoByID")
@ResponseBody
public Map<String, Object> getBuildingInfoByID(HttpServletRequest request,
Long buildingID) throws Exception {
// 从session拿到token,再解密得到userid
Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
// 按照userID来显示该用户登录时显示的建筑
BuildingInfo buildingInfos;
Map<String, Object> map = new HashMap<>();
if (loginInfo != null) {
buildingInfos = buildingInfoService
.getBuildingInfoByBuildingID(buildingID);
map.put("code", 200);
map.put("data", buildingInfos);
} else {
map.put("code", 401);
map.put("data", null);
}
return map;
}
/**
* @api {get} /build/updateBuildingInfo 根据建筑id来修改建筑的信息
* @apiName updateBuildingInfo
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiParam {String} buildingInfo 某个建筑单元的更新后的信息
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "code": 200,
* "result": true/false
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": false
* }
*/
@RequestMapping(value = "/updateBuildingInfo")
@ResponseBody
public Map<String, Object> getBuildingInfoByID(HttpServletRequest request,
String buildingInfo) throws Exception {
// 从session拿到token,再解密得到userid
Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
// 按照userID来显示该用户登录时显示的建筑
Boolean result;
Map<String, Object> map = new HashMap();
if (loginInfo != null) {
result = buildingInfoService.updateBuildingInfo(buildingInfo);
map.put("code", 200);
map.put("result", result);
} else {
map.put("code", 401);
map.put("result", false);
}
return map;
}
/**
* @api {get} /build/getUpperBuilding 获取上级建筑的相关信息
* @apiName getUpperBuilding
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiParam {String} upperBuilding 上级建筑单元的json数据信息
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* "code": 200,
* "result": true/false
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": false
* }
*/
@ResponseBody
@RequestMapping(value = "/getUpperBuilding", produces = "application/json;charset=UTF-8")
public String getUpperBuilding(HttpServletRequest request,
String upperBuilding) throws Exception {
JSONObject jsonObject = JSONObject.parseObject(upperBuilding);
return jsonObject.toJSONString();
}
/**
* @api {get} /build/saveChildBuildInfo 保存下级建筑的添加信息
* @apiName saveChildBuildInfo
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiParam {String} childBuild 下级建筑单元的json数据信息
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* “code": 200,
* "result": true/false
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": false
* }
*/
@ResponseBody
@RequestMapping(value = "/saveChildBuildInfo")
public Map<String, Object> saveChildBuildInfo(HttpServletRequest request,
String childBuild) throws Exception {
// 从session拿到token,再解密得到userid
Map<String, Object> map = new HashMap();
Long userID = AuthUtil.getUserId(request);
if (userID != null) {
// 利用创建人和下级建筑信息添加下级建筑
childBuild = childBuild.substring(1, childBuild.length() - 1);//去除引号
childBuild = childBuild.replace("\\", "");
boolean result = buildingInfoService.addChildBuild(userID, childBuild);
map.put("code", 200);
map.put("result", result);
} else {
map.put("code", 401);
map.put("result", false);
}
return map;
}
/**
* @api {get} /build/deleteBuild 删除建筑
* @apiName deleteBuild
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiParam {Number} buildingID 建筑单元ID
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* “code": 200,
* "result": true/false
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": false
* }
*/
@ResponseBody
@RequestMapping(value = "/deleteBuild")
public Map<String, Object> deleteBuild(HttpServletRequest request, Long buildingID) throws Exception {
// 从session拿到token,再解密得到userid
Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
Map<String, Object> map = new HashMap();
// 按照userID来显示该用户登录时显示的建筑
//Boolean result;
if (loginInfo != null) {
boolean result = buildingInfoService.deleteBuildingInfo(buildingID);
map.put("code", 200);
map.put("result", result);
} else {
map.put("code", 401);
map.put("result", false);
}
return map;
}
/**
* @api {get} /build/setLngAndLat 将建筑位置的地图坐标(经度,纬度)保存
* @apiName setLngAndLat
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiParam {String} coordinate 经纬度信息json数据
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* “code": 200,
* "result": true/false
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* "code": 401,
* "data": false
* }
*/
@ResponseBody
@RequestMapping(value = "/setLngAndLat", produces = "application/json;charset=UTF-8")
public Map<String, Object> setLngAndLat(HttpServletRequest request, String coordinate) throws Exception {
// 从session拿到token,再解密得到userid
Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
Map<String, Object> map = new HashMap();
if (loginInfo != null) {
// 将地图坐标(经纬度)保存入建筑信息
boolean result = buildingInfoService.saveLngAndLat(coordinate);
map.put("code", 200);
map.put("result", result);
} else {
map.put("code", 401);
map.put("result", false);
}
return map;
}
/**
* @api {get} /build/getBulidInfoByUser 获取用户所在机构对应的建筑单元
* @apiName getBulidInfoByUser
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* json数据
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* null/[]
* }
*/
@RequestMapping(value = "/getBulidInfoByUser", produces = "application/json;charset=UTF-8")
@ResponseBody
public List<BuildingInfo> getBulidInfoByUser(HttpServletRequest request) throws Exception {
//从session拿到token,再解密得到userid
Long userID = AuthUtil.getUserId(request);
List<BuildingInfo> buildingInfos = buildingInfoService.getBuildInfoByUser(userID);
return buildingInfos;
}
/**
* @api {get} /build/getALLbuilingType 获取所有的建筑类型
* @apiName getALLbuilingType
* @apiGroup build
* @apiVersion 1.0.0
*
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* [
* {
* “code”: 200,
* "data": "json数据"
* }
* ]
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 401 UNAUTHORIZED
* {
* “code”: 401,
* "data": null
* }
*/
@RequestMapping(value = "/getALLbuilingType")
@ResponseBody
public Map<String, Object> getALLbuilingType(HttpServletRequest request) throws Exception {
Map<String, Object> loginInfo = AuthUtil.getClientLoginInfo(request);
Map<String, Object> map = new HashMap();
if (loginInfo != null) {
List<BuildingType> buildingTypes = buildingInfoService.getALLbuilingType();
map.put("code", 200);
map.put("data", buildingTypes);
} else {
map.put("code", 401);
map.put("data", null);
}
return map;
}
public BuildingInfoService getBuildingInfoService() {
return buildingInfoService;
}
public void setBuildingInfoService(BuildingInfoService buildingInfoService) {
this.buildingInfoService = buildingInfoService;
}
}