support auto mark file download

TongchengOpenSource · May 28, 2021 · 05f1432 · 05f1432
1 parent e67e464
commit 05f1432
Show file tree

Hide file tree

Showing 7 changed files with 54 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,14 @@
 ## smart-doc版本
 
+#### 版本号：2.1.9
+
+- 更新日期: 2020-05-29
+- 更新内容：
+  1. 修复inlineEnum为false时枚举展示在参数中的问题。
+  2. 返回Spring文件下载对象支持自动识别为文件下载，减少手动标记@download tag。
 #### 版本号：2.1.8
 
-- 更新日期: 2020-05-17
+- 更新日期: 2020-05-22
 - 更新内容：
     1. 修复推送接口到torna丢失部分mock值的问题。
     2. 修复在参数注释中配置类替换时将非类名解析成类名的bug 。

diff --git a/src/main/java/com/power/doc/helper/JsonBuildHelper.java b/src/main/java/com/power/doc/helper/JsonBuildHelper.java
@@ -57,6 +57,10 @@ public static String buildReturnJson(DocJavaMethod docJavaMethod, ProjectDocConf
         if (method.getReturns().isVoid() && Objects.isNull(builder.getApiConfig().getResponseBodyAdvice())) {
             return "Doesn't return a value.";
         }
+        DocletTag downloadTag = method.getTagByName(DocTags.DOWNLOAD);
+        if (Objects.nonNull(downloadTag)) {
+            return "File download.";
+        }
         String returnTypeGenericCanonicalName = method.getReturnType().getGenericCanonicalName();
         if (Objects.nonNull(builder.getApiConfig().getResponseBodyAdvice())
                 && Objects.isNull(method.getTagByName(IGNORE_RESPONSE_BODY_ADVICE))) {
@@ -69,6 +73,10 @@ public static String buildReturnJson(DocJavaMethod docJavaMethod, ProjectDocConf
         }
         ApiReturn apiReturn = DocClassUtil.processReturnType(returnTypeGenericCanonicalName);
         String typeName = apiReturn.getSimpleName();
+        if (JavaClassValidateUtil.isFileDownloadResource(typeName)) {
+            docJavaMethod.setDownload(true);
+            return "File download.";
+        }
         Map<String, JavaType> actualTypesMap = docJavaMethod.getActualTypesMap();
         String returnType = apiReturn.getGenericCanonicalName();
         if (Objects.nonNull(actualTypesMap)) {

diff --git a/src/main/java/com/power/doc/helper/ParamsBuildHelper.java b/src/main/java/com/power/doc/helper/ParamsBuildHelper.java
@@ -550,7 +550,6 @@ private static String handleEnumComment(JavaClass javaClass, ProjectDocConfigBui
             }
         } else {
             enumComments = DocUtil.replaceNewLineToHtmlBr(enumComments);
-            comment = comment + "<br/>" + JavaClassUtil.getEnumParams(javaClass) + "<br/>";
             if (StringUtil.isNotEmpty(enumComments)) {
                 comment = comment + "(See: " + enumComments + ")";
             }

diff --git a/src/main/java/com/power/doc/model/DocJavaMethod.java b/src/main/java/com/power/doc/model/DocJavaMethod.java
@@ -41,6 +41,8 @@ public class DocJavaMethod {
 
     private Map<String, JavaType> actualTypesMap;
 
+    private boolean download;
+
     public static DocJavaMethod builder() {
         return new DocJavaMethod();
     }
@@ -80,4 +82,13 @@ public DocJavaMethod setRequestSchema(Map<String, Object> requestSchema) {
         this.requestSchema = requestSchema;
         return this;
     }
+
+    public boolean isDownload() {
+        return download;
+    }
+
+    public DocJavaMethod setDownload(boolean download) {
+        this.download = download;
+        return this;
+    }
 }
diff --git a/src/main/java/com/power/doc/template/IDocBuildTemplate.java b/src/main/java/com/power/doc/template/IDocBuildTemplate.java
@@ -99,6 +99,10 @@ default List<ApiParam> buildReturnApiParams(DocJavaMethod docJavaMethod, Project
         if (method.getReturns().isVoid() && Objects.isNull(projectBuilder.getApiConfig().getResponseBodyAdvice())) {
             return new ArrayList<>(0);
         }
+        DocletTag downloadTag = method.getTagByName(DocTags.DOWNLOAD);
+        if (Objects.nonNull(downloadTag)) {
+            return new ArrayList<>(0);
+        }
         String returnTypeGenericCanonicalName = method.getReturnType().getGenericCanonicalName();
         if (Objects.nonNull(projectBuilder.getApiConfig().getResponseBodyAdvice())
                 && Objects.isNull(method.getTagByName(IGNORE_RESPONSE_BODY_ADVICE))) {

diff --git a/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java b/src/main/java/com/power/doc/template/SpringBootDocBuildTemplate.java
@@ -107,10 +107,7 @@ public ApiDoc getSingleApiData(ProjectDocConfigBuilder projectBuilder, String ap
 
     @Override
     public boolean ignoreReturnObject(String typeName, List<String> ignoreParams) {
-        if (JavaClassValidateUtil.isMvcIgnoreParams(typeName, ignoreParams)) {
-            return DocGlobalConstants.MODE_AND_VIEW_FULLY.equals(typeName);
-        }
-        return false;
+        return JavaClassValidateUtil.isMvcIgnoreParams(typeName, ignoreParams);
     }
 
     private List<ApiMethodDoc> buildControllerMethod(final JavaClass cls, ApiConfig apiConfig,
@@ -237,6 +234,10 @@ private List<ApiMethodDoc> buildControllerMethod(final JavaClass cls, ApiConfig
             apiMethodDoc.setRequestUsage(requestJson == null ? requestExample.getUrl() : requestJson);
             // build response usage
             apiMethodDoc.setResponseUsage(JsonBuildHelper.buildReturnJson(docJavaMethod, projectBuilder));
+            // auto mark file download
+            if (Objects.isNull(docletTag)) {
+                apiMethodDoc.setDownload(docJavaMethod.isDownload());
+            }
             // build response params
             List<ApiParam> responseParams = buildReturnApiParams(docJavaMethod, projectBuilder);
             if (paramsDataToTree) {

diff --git a/src/main/java/com/power/doc/utils/JavaClassValidateUtil.java b/src/main/java/com/power/doc/utils/JavaClassValidateUtil.java
@@ -213,6 +213,22 @@ public static boolean isIgnoreTag(String tagName) {
         }
     }
 
+    /**
+     * Download
+     * @param typeName return type name
+     * @return
+     */
+    public static boolean isFileDownloadResource(String typeName){
+        switch (typeName) {
+            case "org.springframework.core.io.Resource":
+            case "org.springframework.core.io.InputStreamSource":
+            case "org.springframework.core.io.ByteArrayResource":
+                return true;
+            default:
+                return false;
+        }
+    }
+
     /**
      * ignore param of spring mvc
      *
@@ -236,6 +252,9 @@ public static boolean isMvcIgnoreParams(String paramType, List<String> ignorePar
             case "org.springframework.web.reactive.function.server.ServerRequest":
             case "org.springframework.web.multipart.MultipartHttpServletRequest":
             case "org.springframework.http.HttpHeaders":
+            case "org.springframework.core.io.Resource":
+            case "org.springframework.core.io.InputStreamSource":
+            case "org.springframework.core.io.ByteArrayResource":
                 return true;
             default:
                 return false;