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/