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