如何使用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; } }