apidoc 接口文档生成工具

apidoc 接口文档生成工具

以前编写代码的时候，编写文档非常麻烦。
最近写项目的时候，用了apiDoc文档生成工具，感觉还不错。
1.首先要安装nodejs安装nodejs方式

2.安装apidoc

npm install apidoc -g

3.在java项目根目录新建package.json和一个genAPIdoc.bat(这个文件可以不在根目录)文件

package.json文件内容如下：

{
	"name": "接口文档名称",
	"version": "版本号",
	"description":"接口描述",
	"title": "接口标题",
	"url": "https://127.0.0.1:8080/",
	"sampleUrl": "https://127.0.0.1:8080/"
}

genAPIdoc.bat批处理文件的作用：指定生成的文档位置，具体内容如下：

apidoc -i D:\worksp\myProject -o D:\worksp\myProject\apidoc

Pause

4.编写java代码
（1）在controller层方法注释如下

/**
	 * 通过http的get方式获取accessToken
	 * {@link com.ccn.apidoc.httpJson.GetToken#apiDoc}
	 * @param request  
	 * @param param
	 * @return
	 */
	@GetMapping("token")
	@ResponseBody
	public Object getToken(HttpServletRequest request, @RequestParam 		  Map<String,String> param){
		return demoService.getAccessToken(request,param);
	}

(2).在com.ccn.apidoc.httpJson目录下新建GetToken.java文件

package com.ccn.apidoc.httpJson;

public class GetToken {

	/**
     * @api {get} http://ip:port/myproject/base/token?grantType=grantType&appId=:appId&appSecret=:appSecret 基于http+json格式 
     * @apiGroup 获取token
     *
     * @apiParam {String(32)} grantType 获取token填写grantType
     * @apiParam {String(64)} appId 应用ID
     * @apiParam {String(128)} appSecreat 应用秘钥
     * @apiParamExample {json} 响应示例:
     *     {
		        "returnCode": "100",
		        "returnMsg": "token",
		        "data": {
		            "expiresIn": "1000",
		            "token": "4KORBPhEkC11RcNx48ObMEAjL8l6BbR3J4xOWjc11dWIBrn73fFR3b4laxOFJIRN0"
		        }
    		}
     *
     * @apiSuccess (返回说明) {String(8)} returnCode 返回状态，200-成功，其他为失败
     * @apiSuccess (返回说明) {String(2000)} returnMsg 返回状态描述（例如：成功 or 失败原因）
     * @apiSuccess (返回说明) {Object} data 数据域
     * 
     * @apiSuccess (data) {String(128)} token获取到的凭证
     * @apiSuccess (data) {String(8)} expiresIn 凭证有效时间，单位：秒
     * 
     **/
	void apiDoc() {}
}

5.执行genAPIdoc.bat批处理文件


6.优化
可以发现我在用@apiGroup注解的时候，明明写的‘获取token’，怎么在分组的时候是token呢？
我们找到apidoc的安装目录里的C:\Users\ThinkPad\AppData\Roaming\npm\node_modules\apidoc\node_modules\apidoc-core\lib\workers\api_group.js文件
打开api_group.js文件，注释掉下面这段代码：

将原来生成的apidoc文件目录删掉，重新执行genAPIdoc.bat批处理文件


ok，完美。如果还有不是很明白的，请参考apidoc官方文档apidoc