通过apidoc自动生成接口文档

npm install apidoc@0.28.1 -g

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public class ApiDocDemo {
/**
* @apiVersion 1.0.0
* @api {post}{POST} /register 注册用户
* @apiGroup User
* @apiDescription 注册用户
* @apiSampleRequest off
* @apiParam (请求参数) {String} account 用户账户名
* @apiSuccess (响应数据) {String} msg 信息
*
*/
public void doc() {
return doc();
}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "name": "apidoc-demo", 
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "author": "Eve",
  "license": "MIT",
  "apidoc": { 
    "name": "UmeApi接口文档demo", //文档名称
    "description": "You write something here to describe your project", //文档描述
    "title": "The title of this doc", // 形成的浏览器页面标题
    "url": "http://", //api的前缀路径
    "sampleUrl": "http://localhost:3300", // 页面测试api请求的url前缀，会覆盖useHostUrlAsSampleUrl - 这个配置项不设置的话，内部的@apiSampleRequest设置也不起作用
    
    //api-name排序或者group-name排序, 先进行group排序-再进行name排序, 没有的则自动在后面显示
    "order":[
    ],
    "template": {
    "forceLanguage": "zh_cn",// 生成apidoc的默认语言，默认zh_cn（中文简体）
    "withCompare": true,// 是否需要进行版本对比，默认true
    "withGenerator": true,// 是否需要显示编译信息（主要是编译日期和apidoc版本），默认true
    "aloneDisplay": false // 是否需要单独显示某个api，默认false
    }
  }
}

1
apidoc -i apisrc/ -o apidoc/

1
2
3
4
5
<!-- 引入freemarker模板引擎的依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-freemarker</artifactId>
</dependency>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 是否开启thymeleaf缓存,本地为false，生产建议为true
spring.freemarker.cache=false
spring.freemarker.charset=UTF-8
spring.freemarker.allow-request-override=false
spring.freemarker.check-template-location=true
    
#类型
spring.freemarker.content-type=text/html
spring.freemarker.expose-request-attributes=true
spring.freemarker.expose-session-attributes=true
    
#文件后缀
spring.freemarker.suffix=.ftl
#路径
spring.freemarker.template-loader-path=classpath:/templates/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
package com.taobao.rigel.rap.controller;
import java.util.Map;
public class ApiDocDemo {
/**
* @apiVersion ${apiVersion}
* @api {${method}} ${url} ${title}
* @apiGroup ${group}
* @apiDescription ${description}
* @apiSampleRequest off
<#list apiParamsList as apiParam>
    * @apiParam (请求参数) {${apiParam.type}} ${apiParam.field}=${apiParam.mock} ${apiParam.description}
</#list>
*
<#list apiSuccessList as apiSuccess>
    * @apiSuccess (响应数据) {${apiSuccess.type}} ${apiSuccess.field}=${apiSuccess.mock} ${apiSuccess.description}
</#list>
*
*/
public void doc() {
return doc();
}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
    @RequestMapping(value = "/shareApiDoc", method = RequestMethod.GET)
    public Map<String, Object> shareApiDoc(@RequestParam(value = "actionId") int actionId) {

        // step1 创建freeMarker配置实例
        Configuration configuration = new Configuration();
        Writer out = null;
        try {
            // step2 获取模版路径
            configuration.setDirectoryForTemplateLoading(new File(TEMPLATE_PATH));
            // step3 创建数据模型
            Map<String, Object> dataMap = new HashMap<String, Object>();
            //assemble apidoc base info
            dataMap.put("apiVersion", apiVersion);
            dataMap.put("method", requestType);
            dataMap.put("url", actionInfo.getRequestUrl());
            dataMap.put("title", actionInfo.getName());
            dataMap.put("group", page.getName());
            dataMap.put("description", actionInfo.getDescription());
            //get apiParamsList
            List<ApiParam> apiParams = new ArrayList<>();
            dataMap.put("apiParamsList", apiParams);
            //get apiSuccessList
            List<ApiParam> apiSuccess = new ArrayList<>();
            dataMap.put("apiSuccessList", apiSuccess);
            // step4 加载模版文件
            Template template = configuration.getTemplate("test.ftl");
            // step5 生成数据 output to apisrc directory
            File docFile = new File(fileSrc.getPath() + "/" + actionInfo.getName() + nowTime + ".java");
            out = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(docFile)));
            template.process(dataMap, out);
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            try {
                if (null != out) {
                    out.flush();
                }
            } catch (Exception e2) {
                e2.printStackTrace();
            }
        }
        return null;
    }

 graph TD
A[api文档分享] -->B[获取接口数据] --> C[根据模板生成java文件] -->D[根据java文件生成html]-->E[上传到服务器对应的目录中]

1
{"Block":3,"Element":"@apiSuccess","File":"app/routes/user.js","Source":"@apiSuccess {String}   错误提示","level":"error","message":"Empty parser result."}

1
\u4e00-\u9fa5

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
  // grouped by group and name
  var apiByGroupAndName = {};
  let entryName = new Set([]);
  var i=0;
  $.each(apiByGroup, function (index, entries) {
    apiByGroupAndName[index] = _.groupBy(entries, function (entry) {
        i++;
        if(entryName.has(entry.name)){
          
            entry.name=entry.name+i;
            entryName.add(entry.name);
        }
        entryName.add(entry.name);
      return entry.name;
    });
  });

1
2
        type:                '([a-zA-Z0-9\(\)#:\\.\\/\\\\\\[\\]_\|-]+)', // 2
        type:                '(.+?)', // 2

1
* @apiSampleRequest off

相关文章