feat: add group

2021-08-01 23:19:39 +08:00 · 2021-08-01 23:19:39 +08:00 · 388c178662
parent 44397612c4
commit 388c178662
14 changed files with 799 additions and 82 deletions
--- a/src/main/java/com/power/doc/builder/AdocDocBuilder.java
+++ b/src/main/java/com/power/doc/builder/AdocDocBuilder.java
@ -31,6 +31,7 @@ import com.power.doc.template.SpringBootDocBuildTemplate;
 import com.thoughtworks.qdox.JavaProjectBuilder;

 import java.util.List;
+import java.util.stream.Collectors;

 import static com.power.doc.constants.DocGlobalConstants.*;

@ -71,6 +72,7 @@ public class AdocDocBuilder {
        List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
        if (config.isAllInOne()) {
            String docName = builderTemplate.allInOneDocName(config,INDEX_DOC,".doc");
+            apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);
            builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_ADOC_TPL, docName);
        } else {
            builderTemplate.buildApiDoc(apiDocList, config, API_DOC_ADOC_TPL, API_EXTENSION);
--- a/src/main/java/com/power/doc/builder/ApiDocBuilder.java
+++ b/src/main/java/com/power/doc/builder/ApiDocBuilder.java
@ -31,6 +31,7 @@ import com.power.doc.template.SpringBootDocBuildTemplate;
 import com.thoughtworks.qdox.JavaProjectBuilder;

 import java.util.List;
+import java.util.stream.Collectors;

 import static com.power.doc.constants.DocGlobalConstants.*;

@ -70,6 +71,7 @@ public class ApiDocBuilder {
        if (config.isAllInOne()) {
            String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DATE_FORMAT);
            String docName = builderTemplate.allInOneDocName(config,"AllInOne" + version + ".md",".md");
+            apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);
            builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, ALL_IN_ONE_MD_TPL, docName);
        } else {
            builderTemplate.buildApiDoc(apiDocList, config, API_DOC_MD_TPL, API_EXTENSION);
--- a/src/main/java/com/power/doc/builder/DocBuilderTemplate.java
+++ b/src/main/java/com/power/doc/builder/DocBuilderTemplate.java
@ -169,6 +169,7 @@ public class DocBuilderTemplate extends BaseDocBuilderTemplate {
            apiDoc1.setList(new ArrayList<>(0));
            apiDoc1.setLink("error_code_list");
            apiDoc1.setAlias("error");
+            apiDoc1.setGroup(apiDoc1.getDesc());
            apiDocs.add(apiDoc1);
        }
        // set dict list
@ -178,6 +179,7 @@ public class DocBuilderTemplate extends BaseDocBuilderTemplate {
        apiDoc1.setLink("dict_list");
        apiDoc1.setAlias("dict");
        apiDoc1.setDesc(titleMap.get(TemplateVariable.DICT_LIST_TITLE.getVariable()));
+        apiDoc1.setGroup(apiDoc1.getDesc());
        List<ApiMethodDoc> methodDocs = new ArrayList<>();
        for (ApiDocDict apiDocDict : apiDocDictList) {
            ApiMethodDoc methodDoc = new ApiMethodDoc();
--- a/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java
+++ b/src/main/java/com/power/doc/builder/HtmlApiDocBuilder.java
@ -27,13 +27,14 @@ import com.power.doc.factory.BuildTemplateFactory;
 import com.power.doc.model.ApiConfig;
 import com.power.doc.model.ApiDoc;
 import com.power.doc.template.IDocBuildTemplate;
-import com.power.doc.template.SpringBootDocBuildTemplate;
 import com.power.doc.utils.BeetlTemplateUtil;
 import com.thoughtworks.qdox.JavaProjectBuilder;
 import org.apache.commons.lang3.StringUtils;
 import org.beetl.core.Template;

 import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Collectors;

 import static com.power.doc.constants.DocGlobalConstants.*;

@ -74,6 +75,7 @@ public class HtmlApiDocBuilder {
        Template indexCssTemplate = BeetlTemplateUtil.getByName(ALL_IN_ONE_CSS);
        FileUtil.nioWriteFile(indexCssTemplate.render(), config.getOutPath() + FILE_SEPARATOR + ALL_IN_ONE_CSS);
        if (config.isAllInOne()) {
+            apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);
            if (config.isCreateDebugPage()) {
                INDEX_HTML = DEBUG_PAGE_ALL_TPL;
                if (StringUtils.isNotEmpty(config.getAllInOneDocFileName())) {
--- a/src/main/java/com/power/doc/builder/TornaBuilder.java
+++ b/src/main/java/com/power/doc/builder/TornaBuilder.java
@ -80,6 +80,7 @@ public class TornaBuilder {
        ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
        IDocBuildTemplate docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
        List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
+        apiDocList = docBuildTemplate.handleApiGroup(apiDocList, config);
        buildTorna(apiDocList, config, javaProjectBuilder);
    }

@ -94,9 +95,13 @@ public class TornaBuilder {
        TornaApi tornaApi = new TornaApi();
        tornaApi.setAuthor(StringUtil.isEmpty(apiConfig.getAuthor()) ? System.getProperty("user.name") : apiConfig.getAuthor());
        Apis api;
-        List<Apis> apisList = new ArrayList<>();
+        List<Apis> groupApiList = new ArrayList<>();
        //添加接口数据
-        for (ApiDoc a : apiDocs) {
+        for (ApiDoc groupApi : apiDocs) {
+
+            List<Apis> apisList = new ArrayList<>();
+            List<ApiDoc> childrenApiDocs = groupApi.getChildrenApiDocs();
+            for (ApiDoc a : childrenApiDocs) {
                api = new Apis();
                api.setName(StringUtils.isBlank(a.getDesc()) ? a.getName() : a.getDesc());
                api.setItems(buildApis(a.getList(), TornaUtil.setDebugEnv(apiConfig, tornaApi)));
@ -105,8 +110,17 @@ public class TornaBuilder {
                api.setOrderIndex(a.getOrder());
                apisList.add(api);
            }
+            api = new Apis();
+            api.setName(StringUtils.isBlank(groupApi.getDesc()) ? groupApi.getName() : groupApi.getDesc());
+            api.setAuthor(tornaApi.getAuthor());
+            api.setOrderIndex(groupApi.getOrder());
+            api.setIsFolder(TornaConstants.YES);
+            api.setItems(apisList);
+            groupApiList.add(api);
+
+        }
        tornaApi.setCommonErrorCodes(buildErrorCode(apiConfig));
-        tornaApi.setApis(apisList);
+        tornaApi.setApis(groupApiList);
        //推送文档信息
        Map<String, String> requestJson = TornaConstants.buildParams(PUSH, new Gson().toJson(tornaApi), apiConfig);
        //推送字典信息
--- a/src/main/java/com/power/doc/model/ApiConfig.java
+++ b/src/main/java/com/power/doc/model/ApiConfig.java
@ -26,8 +26,10 @@ import com.power.common.util.CollectionUtil;
 import com.power.doc.constants.DocLanguage;
 import com.power.doc.model.rpc.RpcApiDependency;

+import java.util.Arrays;
 import java.util.List;
 import java.util.Objects;
+import java.util.stream.Collectors;

 /**
 * Description:
@ -347,6 +349,8 @@ public class ApiConfig {
     */
    private String framework;

+    private List<ApiGroup> groups;
+
    public String getPathPrefix() {
        return pathPrefix;
    }
@ -440,6 +444,20 @@ public class ApiConfig {
        this.requestHeaders.forEach(header -> header.setDesc(header.getDesc() + "(Global)"));
    }

+    public List<ApiGroup> getGroups() {
+        return groups;
+    }
+
+    public ApiConfig setGroups(List<ApiGroup> groups) {
+        this.groups = groups;
+        return this;
+    }
+
+    public ApiConfig setGroups(ApiGroup... groups) {
+        this.groups = CollectionUtil.asList(groups);
+        return this;
+    }
+
    public List<ApiReqParam> getRequestParams() {
        return requestParams;
    }
--- a/src/main/java/com/power/doc/model/ApiDoc.java
+++ b/src/main/java/com/power/doc/model/ApiDoc.java
@ -57,6 +57,19 @@ public class ApiDoc implements Comparable<ApiDoc> {
     */
    private String[] tags;

+    /**
+     * group
+     *
+     * @author cqmike
+     */
+    private String group;
+
+    /**
+     * class in package name
+     *
+     */
+    private String packageName;
+
    /**
     * List of method doc
     */
@ -74,6 +87,16 @@ public class ApiDoc implements Comparable<ApiDoc> {

    private String author;

+    /**
+     *  if this is group, then is true
+     */
+    private boolean isFolder;
+
+    /**
+     *  children
+     */
+    private List<ApiDoc> childrenApiDocs = new ArrayList<>();
+
    public String getAuthor() {
        return author;
    }
@ -141,6 +164,38 @@ public class ApiDoc implements Comparable<ApiDoc> {
        this.link = link;
    }

+    public String getPackageName() {
+        return packageName;
+    }
+
+    public void setPackageName(String packageName) {
+        this.packageName = packageName;
+    }
+
+    public String getGroup() {
+        return group;
+    }
+
+    public void setGroup(String group) {
+        this.group = group;
+    }
+
+    public boolean isFolder() {
+        return isFolder;
+    }
+
+    public void setFolder(boolean folder) {
+        isFolder = folder;
+    }
+
+    public List<ApiDoc> getChildrenApiDocs() {
+        return childrenApiDocs;
+    }
+
+    public void setChildrenApiDocs(List<ApiDoc> childrenApiDocs) {
+        this.childrenApiDocs = childrenApiDocs;
+    }
+
    @Override
    public int compareTo(ApiDoc o) {
        if (Objects.nonNull(o.getDesc())) {
@ -155,6 +210,7 @@ public class ApiDoc implements Comparable<ApiDoc> {
        apiDoc.setLink(source.getLink());
        apiDoc.setDesc(tag);
        apiDoc.setAuthor(source.getAuthor());
+        apiDoc.setPackageName(source.getPackageName());
        apiDoc.setName(tag);
        apiDoc.setList(new ArrayList<>());
        ApiMethodDoc clone = methodDoc.clone();
@ -164,6 +220,16 @@ public class ApiDoc implements Comparable<ApiDoc> {
    }


+    public static ApiDoc buildGroupApiDoc(String group) {
+        ApiDoc apiDoc = new ApiDoc();
+        apiDoc.setFolder(true);
+        apiDoc.setGroup(group);
+        apiDoc.setName(group);
+        apiDoc.setDesc(group);
+        apiDoc.setChildrenApiDocs(new ArrayList<>());
+        return apiDoc;
+    }
+
    @Override
    public String toString() {
        final StringBuilder sb = new StringBuilder("{");
--- a/src/main/java/com/power/doc/model/ApiGroup.java
+++ b/src/main/java/com/power/doc/model/ApiGroup.java
@ -0,0 +1,55 @@
+package com.power.doc.model;
+
+/**
+ * api group
+ *
+ * @author cqmike
+ * @version 1.0.0
+ * @since 2021年07月31日 16:39:00
+ */
+public class ApiGroup {
+
+    /**
+     * group name
+     */
+    private String name;
+
+    /**
+     * package name
+     * support patten
+     */
+    private String apis;
+
+    /**
+     * url path
+     * support patten
+     */
+    private String paths;
+
+    public String getName() {
+        return name;
+    }
+
+    public ApiGroup setName(String name) {
+        this.name = name;
+        return this;
+    }
+
+    public String getApis() {
+        return apis;
+    }
+
+    public ApiGroup setApis(String apis) {
+        this.apis = apis;
+        return this;
+    }
+
+    public String getPaths() {
+        return paths;
+    }
+
+    public ApiGroup setPaths(String paths) {
+        this.paths = paths;
+        return this;
+    }
+}
--- a/src/main/java/com/power/doc/template/IDocBuildTemplate.java
+++ b/src/main/java/com/power/doc/template/IDocBuildTemplate.java
@ -35,6 +35,8 @@ import com.thoughtworks.qdox.model.JavaMethod;
 import com.thoughtworks.qdox.model.JavaType;

 import java.util.*;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Collectors;

 import static com.power.doc.constants.DocGlobalConstants.NO_COMMENTS_FOUND;
 import static com.power.doc.constants.DocTags.IGNORE_RESPONSE_BODY_ADVICE;
@ -82,6 +84,8 @@ public interface IDocBuildTemplate<T> {
        apiDoc.setName(controllerName);
        apiDoc.setAuthor(classAuthor);
        apiDoc.setAlias(controllerName);
+        apiDoc.setFolder(true);
+        apiDoc.setPackageName(cls.getPackage().getName());
        //apiDoc.setAuthor();

        // handle class tags
@ -99,6 +103,54 @@ public interface IDocBuildTemplate<T> {
    }


+    /**
+     *  handle group api docs
+     *
+     * @author cqmike
+     * @param apiDocList
+     * @param apiConfig
+     */
+    default List<ApiDoc> handleApiGroup(List<ApiDoc> apiDocList, ApiConfig apiConfig) {
+        if (CollectionUtil.isEmpty(apiDocList) || apiConfig == null) {
+            return apiDocList;
+        }
+
+        List<ApiGroup> groups = apiConfig.getGroups();
+        ApiDoc defaultGroup = ApiDoc.buildGroupApiDoc("default");
+
+        List<ApiDoc> finalApiDocs = new ArrayList<>();
+        finalApiDocs.add(defaultGroup);
+        AtomicInteger order = new AtomicInteger(1);
+        defaultGroup.setOrder(order.getAndIncrement());
+        groups.forEach(group -> {
+
+            ApiDoc groupApiDoc = ApiDoc.buildGroupApiDoc(group.getName());
+            groupApiDoc.setOrder(order.getAndIncrement());
+            finalApiDocs.add(groupApiDoc);
+            apiDocList.forEach(doc -> {
+
+                if (!DocUtil.isMatch(group.getApis(), doc.getPackageName())) {
+                    defaultGroup.getChildrenApiDocs().add(doc);
+                    doc.setOrder(defaultGroup.getChildrenApiDocs().size());
+                    return;
+                }
+                groupApiDoc.getChildrenApiDocs().add(doc);
+                doc.setOrder(groupApiDoc.getChildrenApiDocs().size());
+                doc.setGroup(group.getName());
+                if (StringUtil.isEmpty(group.getPaths())) {
+                    return;
+                }
+                List<ApiMethodDoc> methodDocs = doc.getList().stream()
+                        .filter(l -> DocPathUtil.matches(l.getPath(), group.getPaths(), null))
+                        .collect(Collectors.toList());
+                doc.setList(methodDocs);
+            });
+        });
+
+        return finalApiDocs;
+    }
+
+
    default List<ApiParam> buildReturnApiParams(DocJavaMethod docJavaMethod, ProjectDocConfigBuilder projectBuilder) {
        JavaMethod method = docJavaMethod.getJavaMethod();
        if (method.getReturns().isVoid() && Objects.isNull(projectBuilder.getApiConfig().getResponseBodyAdvice())) {
--- a/src/main/resources/template/AllInOne.adoc
+++ b/src/main/resources/template/AllInOne.adoc
@ -17,26 +17,30 @@ for(revisionLog in revisionLogList){


 <%
-for(api in apiDocList){
+for(apiGroup in apiDocList){
 %>
-== ${api.desc}
+== ${apiGroup.group}
+<%
+for(api in apiGroup.childrenApiDocs){
+%>
+=== ${api.desc}
 <%
 for(doc in api.list){
 %>
 <%if(doc.deprecated){%>
-=== [line-through]#${doc.desc}#
+==== [line-through]#${doc.desc}#
 <%}else{%>
-=== ${doc.desc}
+==== ${doc.desc}
 <%}%>
-*URL:* ${doc.url}
+*URL:* `${doc.url}`

-*Type:* ${doc.type}
+*Type:* `${doc.type}`

 <%if(isNotEmpty(doc.author)){%>
 *Author:* ${doc.author}
 <%}%>

-*Content-Type:* ${doc.contentType}
+*Content-Type:* `${doc.contentType}`

 <%if(isNotEmpty(doc.headers)){%>
 *Request-headers:*
@ -122,6 +126,7 @@ ${doc.responseUsage}
 ----
 <%}%>

+<% } %>
 <% } %>
 <% } %>
 <%if(isNotEmpty(errorCodeList)){%>
--- a/src/main/resources/template/AllInOne.btl
+++ b/src/main/resources/template/AllInOne.btl
@ -14,7 +14,11 @@ ${revisionLog.version}|${revisionLog.revisionTime}|${revisionLog.status}|${revis


 <%
-for(api in apiDocList){
+for(apiGroup in apiDocList){
+%>
+# ${apiGroup.group}
+<%
+for(api in apiGroup.childrenApiDocs){
 %>
 ## ${api.desc}
 <%
@ -106,6 +110,7 @@ ${doc.responseUsage}
 ```
 <%}%>

+<% } %>
 <% } %>
 <% } %>
 <%if(isNotEmpty(errorCodeList)){%>
--- a/src/main/resources/template/debug-all.html
+++ b/src/main/resources/template/debug-all.html
--- a/src/main/resources/template/js/search_all.js.btl
+++ b/src/main/resources/template/js/search_all.js.btl
@ -1,6 +1,12 @@
 let api = [];
-<%for(api in apiDocList){%>
+<%for(apiGroup in apiDocList) {%>
 api.push({
+    name: '${apiGroup.group}',
+    order: '${apiGroup.order}',
+    list: []
+})
+<%for(api in apiGroup.childrenApiDocs) {%>
+api[${apiGroupLP.dataIndex}].list.push({
    alias: '${api.alias}',
    order: '${api.order}',
    link: '${removeLineBreaks(api.link)}',
@ -8,12 +14,13 @@ api.push({
    list: []
 })
 <%for(doc in api.list) {%>
-api[${apiLP.dataIndex}].list.push({
+api[${apiGroupLP.dataIndex}].list[${apiLP.dataIndex}].list.push({
    order: '${doc.order}',
    desc: '${removeLineBreaks(doc.desc)}',
 });
 <%}%>
 <%}%>
+<%}%>
 document.onkeydown = keyDownSearch;
 function keyDownSearch(e) {
    const theEvent = e;
@ -21,9 +28,14 @@ function keyDownSearch(e) {
    if (code == 13) {
        const search = document.getElementById('search');
        const searchValue = search.value;
-        let searchArr = [];
+        let searchGroup = [];
        for (let i = 0; i < api.length; i++) {
-            let apiData = api[i];
+
+            let apiGroup = api[i];
+
+            let searchArr = [];
+            for (let i = 0; i < apiGroup.list.length; i++) {
+                let apiData = apiGroup.list[i];
                const desc = apiData.desc;
                if (desc.indexOf(searchValue) > -1) {
                    searchArr.push({
@ -54,6 +66,15 @@ function keyDownSearch(e) {
                    }
                }
            }
+            if (searchArr.length === 0) {
+                continue;
+            }
+            searchGroup.push({
+                name: apiGroup.name,
+                order: apiGroup.order,
+                list: searchArr
+            });
+        }
        let html;
        if (searchValue == '') {
            const liClass = "";
@ -63,7 +84,7 @@ function keyDownSearch(e) {
        } else {
            const liClass = "open";
            const display = "display: block";
-            html = buildAccordion(searchArr,liClass,display);
+            html = buildAccordion(searchGroup,liClass,display);
            document.getElementById('accordion').innerHTML = html;
        }
        const Accordion = function (el, multiple) {
@ -85,10 +106,17 @@ function keyDownSearch(e) {
    }
 }

-function buildAccordion(apiData, liClass, display) {
+function buildAccordion(apiGroups, liClass, display) {
    let html = "";
    let doc;
-    if (apiData.length > 0) {
+    if (apiGroups.length > 0) {
+        for (let i = 0; i < apiGroups.length; i++) {
+            let apiGroup = apiGroups[i];
+            html += '<li class="'+liClass+'">';
+            html += '<a class="dd" href="#_' + apiGroup.name + '">' + apiGroup.order + '.&nbsp;' + apiGroup.name + '</a>';
+            html += '<ul class="sectlevel1">';
+
+            let apiData = apiGroup.list;
            for (let j = 0; j < apiData.length; j++) {
                html += '<li class="'+liClass+'">';
                html += '<a class="dd" href="#_' + apiData[j].link + '">' + apiData[j].order + '.&nbsp;' + apiData[j].desc + '</a>';
@ -100,6 +128,10 @@ function buildAccordion(apiData, liClass, display) {
                html += '</ul>';
                html += '</li>';
            }
+
+            html += '</ul>';
+            html += '</li>';
+        }
    }
    return html;
 }
--- a/src/test/java/com/power/doc/ApiDocTest.java
+++ b/src/test/java/com/power/doc/ApiDocTest.java
@ -102,7 +102,7 @@ public class ApiDocTest {
        //OpenApiBuilder.buildOpenApi(config);
        HtmlApiDocBuilder.buildApiDoc(config);
        //RpcTornaBuilder.buildApiDoc(config);
-        TornaBuilder.buildApiDoc(config);
+//        TornaBuilder.buildApiDoc(config);
        // RpcHtmlBuilder.buildApiDoc(config);
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);