在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具,so来介绍一下!
一.安装Apidoc
1.安装nmp环境,Windows环境可直接通过http://nodejs.org/下载安装包安装 (这一步是安装node.js环境,直接下一步安装就是了)
2.安装后在cmd终端执行npm install apidoc -g
二.apidoc使用
3、cmd 在dos窗口执行命令
该工具是Nodejs的模块,请务必在使用前安装好nodejs环境!
nodejs的apidocjs的api文档
一.安装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文档