apidoc 生成Restful web Api文档

在项目开发过程中，总会牵扯到接口文档的设计与编写，之前使用的都是office工具，写一个文档，总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具，so来介绍一下！ 

该工具是Nodejs的模块，请务必在使用前安装好nodejs环境！

nodejs的apidocjs的api文档

http://apidocjs.com/

一．安装Apidoc


1.安装nmp环境,Windows环境可直接通过http://nodejs.org/下载安装包安装 （这一步是安装node.js环境，直接下一步安装就是了）


2.安装后在cmd终端执行npm install apidoc -g

3.执行成功终端输入npm –v确认是否npm安装成功

二．apidoc使用

1.在项目根目录中创建apidoc.json文件 （笔者的项目为activity  所以我把apidoc.json 放在activity文件夹下）

{
  "name": "项目名称",
  "version": "2.0.0",
  "description": "项目API文档",
  "title": "Custom apiDoc browser title",
  "url" : "http://localhost:8080/v2",
  "sampleUrl": "http://localhost:8080/v2",
  "forceLanguage":"zh-cn",
  "template": {
    "withCompare": true,
    "withGenerator": true
  }
}

2、在对应的接口方法上提交如下注释

    /**
     *
     * @api {post} /tts/apidoc  测试
     * @apiName 测试
     * @apiGroup 测试组
     * @apiVersion 2.0.0
     * @apiDescription 接口详细描述
     *
     * @apiParam {String} id 用户ID
     *
     * @apiSuccess {String} status 结果码
     * @apiSuccess {String} msg 消息说明
     * @apiSuccessExample Success-Response:
     *  HTTP/1.1 200 OK
     * {
     * status:0,
     * msg:'success',
     * data:{}
     *  }
     *
     *  @apiError All 对应<code>id</code>的用户没找到
     *  @apiErrorExample {json} Error-Response:
     *  HTTP/1.1 200
     *  {
     *   code:-1,
     *   msg:'user not found',
     *   }
     */
    @RequestMapping(value = "/apidoc", method = {RequestMethod.GET,RequestMethod.POST})
    public ModelAndView getapidoc(HttpServletRequest request) {
        String id = ServletRequestUtils.getStringParameter(request, "id", "");

        ModelAndView mav = new ModelAndView();
        mav.addObject("name", "Hello World TTS");
        mav.setViewName("/tts/demo01");
        return mav;
    }
	

3、cmd 在dos窗口执行命令

apidoc -i D:\IntelliJIdeaWorkspace\activity -o D:\IntelliJIdeaWorkspace\apidoc

到 apidoc目录下打开index.html查看生成的文档.

三. 生成api文档。

apidoc -i myapp/ -o apidoc/ -t mytemplate/

myapp是当前工作目录下的源码目录

apidoc是用于存放生成出的文档文件的目录

mytemplate是自定义模板文件夹，刚开始用，可以不指定，后面有需要了再研究怎么自定义模板吧。

如果看到“success: Done.”说明生成成功 ，到 apidoc目录下打开index.html查看生成的文档.

效果图：

参考资料：

1、https://my.oschina.net/u/660253/blog/735184

2、http://blog.csdn.net/xumin198908/article/details/41964159

nodejs的apidocjs的api文档

http://apidocjs.com/