Merge remote-tracking branch 'origin/master'

CHANGELOG.md

@@ -1,9 +1,10 @@
 ## smart-doc版本
 
 ### 版本号：3.0.1
-- 更新日期: 2023-10-20
+- 更新日期: 2023-12.xx
 - 更新内容：
-  1. xxx
+  1. 优化Dubbo文档设置，[#649](https://github.com/smart-doc-group/smart-doc/issues/649)
+  2. 优化Dubbo文档中字段类型展示，[#648](https://github.com/smart-doc-group/smart-doc/issues/648)
 
 ### 版本号：3.0.0
 - 更新日期: 2023-10-20

src/main/java/com/ly/doc/builder/BaseDocBuilderTemplate.java

@@ -81,6 +81,7 @@ public void checkAndInit(ApiConfig config, boolean checkOutPath) {
         if (StringUtil.isEmpty(config.getOutPath()) && checkOutPath) {
             throw new RuntimeException("doc output path can't be null or empty");
         }
+        ApiConfig.setInstance(config);
     }
 
     /**

src/main/java/com/ly/doc/builder/DocBuilderTemplate.java

@@ -143,6 +143,7 @@ public Template buildAllRenderDocTemplate(List<ApiDoc> apiDocList, ApiConfig con
         tpl.binding(TemplateVariable.API_DOC_LIST.getVariable(), apiDocList);
         tpl.binding(TemplateVariable.ERROR_CODE_LIST.getVariable(), errorCodeList);
         tpl.binding(TemplateVariable.VERSION_LIST.getVariable(), config.getRevisionLogs());
+        tpl.binding(TemplateVariable.LANGUAGE.getVariable(), config.getLanguage());
         tpl.binding(TemplateVariable.VERSION.getVariable(), now);
         tpl.binding(TemplateVariable.INDEX_ALIAS.getVariable(), index);
         tpl.binding(TemplateVariable.CREATE_TIME.getVariable(), strTime);

src/main/java/com/ly/doc/builder/JMeterBuilder.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright (C) 2018-2023 smart-doc
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.ly.doc.builder;
+
+import com.ly.doc.constants.DocGlobalConstants;
+import com.ly.doc.factory.BuildTemplateFactory;
+import com.ly.doc.helper.JavaProjectBuilderHelper;
+import com.ly.doc.model.ApiConfig;
+import com.ly.doc.model.ApiDoc;
+import com.ly.doc.template.IDocBuildTemplate;
+import com.power.common.util.DateTimeUtil;
+import com.thoughtworks.qdox.JavaProjectBuilder;
+
+import java.util.List;
+
+/**
+ * used to generate jmx file for Jmeter
+ * @author Lansg
+ */
+public class JMeterBuilder {
+
+    private static final String API_EXTENSION = ".jmx";
+
+    private static final String DATE_FORMAT = "yyyyMMddHHmm";
+
+    /**
+     * @param config ApiConfig
+     */
+    public static void buildApiDoc(ApiConfig config) {
+        JavaProjectBuilder javaProjectBuilder = JavaProjectBuilderHelper.create();
+        buildApiDoc(config, javaProjectBuilder);
+    }
+
+    /**
+     * Only for smart-doc maven plugin and gradle plugin.
+     *
+     * @param config             ApiConfig
+     * @param javaProjectBuilder ProjectDocConfigBuilder
+     */
+    public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder) {
+        DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
+        builderTemplate.checkAndInit(config, Boolean.TRUE);
+        config.setAdoc(false);
+        config.setShowJavaType(true);
+        config.setParamsDataToTree(false);
+        ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, javaProjectBuilder);
+        IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
+        List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
+        String version = config.isCoverOld() ? "" : "-V" + DateTimeUtil.long2Str(System.currentTimeMillis(), DATE_FORMAT);
+        String docName = builderTemplate.allInOneDocName(config, "JmeterApiDoc" + version + ".jmx", ".jmx");
+        builderTemplate.buildAllInOne(apiDocList, config, javaProjectBuilder, DocGlobalConstants.JMETER_TPL, docName);
+    }
+}

src/main/java/com/ly/doc/builder/PostmanJsonBuilder.java

@@ -256,6 +256,7 @@ private static List<HeaderBean> buildHeaderBeanList(ApiMethodDoc apiMethodDoc) {
 
     private static void postManCreate(ApiConfig config, ProjectDocConfigBuilder configBuilder) {
         IDocBuildTemplate<ApiDoc> docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework());
+        config.setShowJavaType(true);
         List<ApiDoc> apiDocList = docBuildTemplate.getApiData(configBuilder);
         RequestItem requestItem = new RequestItem();
         requestItem.setInfo(new InfoBean(config.getProjectName()));

src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java

@@ -39,6 +39,7 @@
 import com.thoughtworks.qdox.JavaProjectBuilder;
 
 import java.util.*;
+import java.util.stream.Collectors;
 
 import static com.ly.doc.constants.DocGlobalConstants.*;
 
@@ -105,18 +106,25 @@ public Map<String, Object> buildPaths(ApiConfig apiConfig, List<ApiDoc> apiDocLi
         Map<String, Object> pathMap = new HashMap<>(500);
         Set<ApiMethodDoc> methodDocs = DocMapping.METHOD_DOCS;
         for (ApiMethodDoc methodDoc : methodDocs) {
-            String path = methodDoc.getPath();
-            Map<String, Object> request = buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc());
-            if (!pathMap.containsKey(path)) {
-                pathMap.put(path, request);
-            } else {
-                Map<String, Object> oldRequest = (Map<String, Object>) pathMap.get(path);
-                oldRequest.putAll(request);
+            String [] paths = methodDoc.getPath().split(";");
+            for(String path : paths) {
+                path = path.trim();
+                Map<String, Object> request = buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc());
+                if (!pathMap.containsKey(path)) {
+                    pathMap.put(path, request);
+                } else {
+                    Map<String, Object> oldRequest = (Map<String, Object>) pathMap.get(path);
+                    oldRequest.putAll(request);
+                }
             }
         }
         for (Map.Entry<String, TagDoc> docEntry : DocMapping.TAG_DOC.entrySet()) {
             String tag = docEntry.getKey();
-            tags.add(OpenApiTag.of(tag, tag));
+            tags.addAll(docEntry.getValue().getClazzDocs()
+                    .stream()
+                    //optimize tag content for compatible to swagger
+                    .map(doc -> OpenApiTag.of(doc.getName(), doc.getDesc()))
+                    .collect(Collectors.toSet()));
         }
         return pathMap;
     }
@@ -166,7 +174,7 @@ public Map<String, Object> buildContentBody(ApiConfig apiConfig, ApiMethodDoc ap
         } else if (!isRep && Objects.nonNull(apiMethodDoc.getRequestSchema())) {
             content.put("schema", apiMethodDoc.getRequestSchema());
         } else {
-            content.put("schema", buildBodySchema(apiMethodDoc, ComponentTypeEnum.getComponentEnumByCode(apiConfig.getComponentType()), isRep));
+            content.put("schema", buildBodySchema(apiMethodDoc, isRep));
         }
 
         if (OPENAPI_2_COMPONENT_KRY.equals(componentKey) && !isRep) {
@@ -186,7 +194,7 @@ public Map<String, Object> buildContentBody(ApiConfig apiConfig, ApiMethodDoc ap
      * @param apiMethodDoc ApiMethodDoc
      * @param isRep        is response
      */
-    public Map<String, Object> buildBodySchema(ApiMethodDoc apiMethodDoc, ComponentTypeEnum componentTypeEnum, boolean isRep) {
+    public Map<String, Object> buildBodySchema(ApiMethodDoc apiMethodDoc, boolean isRep) {
         Map<String, Object> schema = new HashMap<>(10);
         Map<String, Object> innerScheme = new HashMap<>(10);
         // For response
@@ -204,7 +212,7 @@ public Map<String, Object> buildBodySchema(ApiMethodDoc apiMethodDoc, ComponentT
 
         // for request
         String requestRef;
-        String randomName = ComponentTypeEnum.getRandomName(componentTypeEnum, apiMethodDoc);
+        String randomName = ComponentTypeEnum.getRandomName(ApiConfig.getInstance().getComponentType(), apiMethodDoc);
         if (apiMethodDoc.getContentType().equals(DocGlobalConstants.URL_CONTENT_TYPE)) {
             requestRef = componentKey + OpenApiSchemaUtil.getClassNameFromParams(apiMethodDoc.getQueryParams());
         } else {
@@ -332,7 +340,7 @@ public Map<String, Object> buildResponses(ApiConfig apiConfig, ApiMethodDoc apiM
      *
      * @param apiDocs List of ApiDoc
      */
-    abstract public Map<String, Object> buildComponentsSchema(List<ApiDoc> apiDocs, ComponentTypeEnum componentTypeEnum);
+    abstract public Map<String, Object> buildComponentsSchema(List<ApiDoc> apiDocs);
 
     /**
      * component schema properties
@@ -408,9 +416,7 @@ private Map<String, Object> buildPropertiesData(ApiParam apiParam, Map<String, O
                         propertiesData.put("items", arrayRef);
                     }
                 }
-            }
-            //基础数据类型
-            else {
+            } else {
                 Map<String, Object> arrayRef = new HashMap<>(4);
                 arrayRef.put("type", "string");
                 propertiesData.put("items", arrayRef);
@@ -450,6 +456,7 @@ private Map<String, Object> buildPropertiesData(ApiParam apiParam, Map<String, O
      * @param projectBuilder JavaDocBuilder of QDox
      */
     public List<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectBuilder) {
+        config.setShowJavaType(false);
         DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
         builderTemplate.checkAndInit(config, Boolean.TRUE);
         ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, projectBuilder);

src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java

@@ -22,7 +22,6 @@
  */
 package com.ly.doc.builder.openapi;
 
-import com.ly.doc.constants.ComponentTypeEnum;
 import com.ly.doc.constants.DocGlobalConstants;
 import com.ly.doc.constants.Methods;
 import com.ly.doc.model.*;
@@ -87,7 +86,7 @@ public void openApiCreate(ApiConfig config, List<ApiDoc> apiDocList) {
         Set<OpenApiTag> tags = new HashSet<>();
         json.put("tags", tags);
         json.put("paths", buildPaths(config, apiDocList, tags));
-        json.put("components", buildComponentsSchema(apiDocList, ComponentTypeEnum.getComponentEnumByCode(config.getComponentType())));
+        json.put("components", buildComponentsSchema(apiDocList));
 
         String filePath = config.getOutPath();
         filePath = filePath + DocGlobalConstants.OPEN_API_JSON;
@@ -264,7 +263,7 @@ Map<String, Object> getStringParams(ApiParam apiParam, boolean hasItems) {
     }
 
     @Override
-    public Map<String, Object> buildComponentsSchema(List<ApiDoc> apiDocs, ComponentTypeEnum componentTypeEnum) {
+    public Map<String, Object> buildComponentsSchema(List<ApiDoc> apiDocs) {
         Map<String, Object> schemas = new HashMap<>(4);
         Map<String, Object> component = new HashMap<>();
         component.put(DocGlobalConstants.DEFAULT_PRIMITIVE, STRING_COMPONENT);

src/main/java/com/ly/doc/builder/openapi/SwaggerBuilder.java

@@ -21,7 +21,6 @@
  */
 package com.ly.doc.builder.openapi;
 
-import com.ly.doc.constants.ComponentTypeEnum;
 import com.ly.doc.constants.DocGlobalConstants;
 import com.ly.doc.model.*;
 import com.ly.doc.utils.DocUtil;
@@ -88,7 +87,7 @@ public void openApiCreate(ApiConfig config, List<ApiDoc> apiDocList) {
         Set<OpenApiTag> tags = new HashSet<>();
         json.put("tags", tags);
         json.put("paths", buildPaths(config, apiDocList, tags));
-        json.put("definitions", buildComponentsSchema(apiDocList, ComponentTypeEnum.getComponentEnumByCode(config.getComponentType())));
+        json.put("definitions", buildComponentsSchema(apiDocList));
 
         String filePath = config.getOutPath();
         filePath = filePath + DocGlobalConstants.OPEN_API_JSON;
@@ -138,12 +137,8 @@ public Map<String, Object> buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDo
         Map<String, Object> request = new HashMap<>(20);
         request.put("summary", apiMethodDoc.getDesc());
         request.put("description", apiMethodDoc.getDetail());
-        String tag = StringUtil.isEmpty(apiDoc.getDesc()) ? DocGlobalConstants.OPENAPI_TAG : apiDoc.getDesc();
-        if (StringUtil.isNotEmpty(apiMethodDoc.getGroup())) {
-            request.put("tags", new String[]{tag});
-        } else {
-            request.put("tags", new String[]{tag});
-        }
+        request.put("tags", Arrays.asList(apiDoc.getName(),apiDoc.getDesc(), apiMethodDoc.getGroup())
+                .stream().filter(StringUtil::isNotEmpty).toArray(n->new String[n]));
         List<Map<String, Object>> parameters = buildParameters(apiMethodDoc);
         //requestBody
         if (CollectionUtil.isNotEmpty(apiMethodDoc.getRequestParams())) {
@@ -161,7 +156,8 @@ public Map<String, Object> buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDo
         request.put("responses", buildResponses(apiConfig, apiMethodDoc));
         request.put("deprecated", apiMethodDoc.isDeprecated());
         String operationId = apiMethodDoc.getUrl().replace(apiMethodDoc.getServerUrl(), "");
-        request.put("operationId", String.join("", OpenApiSchemaUtil.getPatternResult("[A-Za-z0-9{}]*", operationId)));
+        //make sure operationId is unique and can be used as a method name
+        request.put("operationId",apiMethodDoc.getName()+"_"+apiMethodDoc.getMethodId()+"UsingOn"+apiMethodDoc.getType());
 
         return request;
     }
@@ -275,7 +271,7 @@ Map<String, Object> getStringParams(ApiParam apiParam, boolean hasItems) {
     }
 
     @Override
-    public Map<String, Object> buildComponentsSchema(List<ApiDoc> apiDocs, ComponentTypeEnum componentTypeEnum) {
+    public Map<String, Object> buildComponentsSchema(List<ApiDoc> apiDocs) {
         Map<String, Object> component = new HashMap<>();
         component.put(DocGlobalConstants.DEFAULT_PRIMITIVE, STRING_COMPONENT);
         apiDocs.forEach(

src/main/java/com/ly/doc/constants/ComponentTypeEnum.java

@@ -57,13 +57,4 @@ public static String getRandomName(ComponentTypeEnum componentTypeEnum, ApiMetho
     public String getComponentType() {
         return componentType;
     }
-
-    public static ComponentTypeEnum getComponentEnumByCode(String code) {
-        for (ComponentTypeEnum typeEnum : ComponentTypeEnum.values()) {
-            if (typeEnum.getComponentType().equals(code)) {
-                return typeEnum;
-            }
-        }
-        return RANDOM;
-    }
 }

src/main/java/com/ly/doc/constants/DocGlobalConstants.java

@@ -42,6 +42,8 @@ public interface DocGlobalConstants {
     String RANDOM_MOCK = "randomMock";
     String API_DOC_MD_TPL = "ApiDoc.md";
 
+    String JMETER_TPL = "JMeter.jmx";
+
     String API_DOC_ADOC_TPL = "ApiDoc.adoc";
 
     String ALL_IN_ONE_MD_TPL = "AllInOne.md";
@@ -213,8 +215,6 @@ public interface DocGlobalConstants {
 
     String ENUM = "enum";
 
-    String DUBBO_SWAGGER = "org.apache.dubbo.rpc.protocol.rest.integration.swagger.DubboSwaggerApiListingResource";
-
     String ARRAY = "array";
     String PARAM_TYPE_FILE = "file";
 

src/main/java/com/ly/doc/constants/DocTags.java

@@ -127,4 +127,14 @@ public interface DocTags {
      * tag @see
      */
     String SEE = "see";
+
+    /**
+     * tag @protocol
+     */
+    String PROTOCOL = "protocol";
+
+    /**
+     * dubbo service name
+     */
+    String SERVICE = "service";
 }

src/main/java/com/ly/doc/constants/DubboAnnotationConstants.java

@@ -38,4 +38,6 @@ public interface DubboAnnotationConstants {
      * support ali dubbo
      */
     String ALI_DUBBO_SERVICE = "com.alibaba.dubbo.config.annotation.Service";
+
+    String DUBBO_SWAGGER = "org.apache.dubbo.rpc.protocol.rest.integration.swagger.DubboSwaggerApiListingResource";
 }

src/main/java/com/ly/doc/constants/TemplateVariable.java

@@ -41,6 +41,7 @@ public enum TemplateVariable {
     ERROR_LIST_TITLE("errorListTitle"),
     CREATE_TIME("createTime"),
     PROJECT_NAME("projectName"),
+    LANGUAGE("language"),
     DICT_LIST("dictList"),
     DICT_LIST_TITLE("dictListTitle"),
     DICT_ORDER("dictListOrder"),