From a02b5437f064d2adef8bb4363c5c68ca52134c31 Mon Sep 17 00:00:00 2001 From: shalousun <836575280@qq.com> Date: Mon, 5 Feb 2024 20:24:42 +0800 Subject: [PATCH] Fix JAX-RS documentation generation bug. --- .../com/ly/doc/helper/DocBuildHelper.java | 3 ++ .../com/ly/doc/model/DocJavaParameter.java | 11 +++++ .../doc/model/dependency/DependencyTree.java | 28 ++++++++++--- .../doc/template/IBaseDocBuildTemplate.java | 16 +++---- .../com/ly/doc/template/IRestDocTemplate.java | 42 +++++++++++-------- .../doc/template/JaxrsDocBuildTemplate.java | 18 ++++---- 6 files changed, 80 insertions(+), 38 deletions(-) diff --git a/src/main/java/com/ly/doc/helper/DocBuildHelper.java b/src/main/java/com/ly/doc/helper/DocBuildHelper.java index e651ad71e..1cacfe48b 100644 --- a/src/main/java/com/ly/doc/helper/DocBuildHelper.java +++ b/src/main/java/com/ly/doc/helper/DocBuildHelper.java @@ -117,6 +117,9 @@ private void writeDependencyTree(List dependencyTree) { } private List mergeDependencyTree(List newDependencyTree) { + if (Objects.isNull(this.dependencyTree.getDependencyTree())) { + return new ArrayList<>(); + } List oldDependencyTree = new ArrayList<>(this.dependencyTree.getDependencyTree()); // remove the deleted or deprecated dependencies diff --git a/src/main/java/com/ly/doc/model/DocJavaParameter.java b/src/main/java/com/ly/doc/model/DocJavaParameter.java index e8fa837cf..7dbb6d6f3 100644 --- a/src/main/java/com/ly/doc/model/DocJavaParameter.java +++ b/src/main/java/com/ly/doc/model/DocJavaParameter.java @@ -34,6 +34,9 @@ public class DocJavaParameter { private String genericCanonicalName; + private String genericFullyQualifiedName; + + private String fullyQualifiedName; private String typeValue; @@ -58,6 +61,14 @@ public void setGenericCanonicalName(String genericCanonicalName) { this.genericCanonicalName = genericCanonicalName; } + public String getGenericFullyQualifiedName() { + return genericFullyQualifiedName; + } + + public void setGenericFullyQualifiedName(String genericFullyQualifiedName) { + this.genericFullyQualifiedName = genericFullyQualifiedName; + } + public String getFullyQualifiedName() { return fullyQualifiedName; } diff --git a/src/main/java/com/ly/doc/model/dependency/DependencyTree.java b/src/main/java/com/ly/doc/model/dependency/DependencyTree.java index ad55d5871..9a6a01503 100644 --- a/src/main/java/com/ly/doc/model/dependency/DependencyTree.java +++ b/src/main/java/com/ly/doc/model/dependency/DependencyTree.java @@ -39,6 +39,12 @@ public class DependencyTree { private static final String CONFIG_NAME = ".smart-doc-dependency.json"; + + /** + * whether increment build + */ + private transient boolean increment; + /** * dependency tree file */ @@ -73,6 +79,11 @@ private DependencyTree() { */ public static DependencyTree detect(String baseDir, boolean isIncrement) { DependencyTree dependencyTree; + if (!isIncrement) { + dependencyTree = new DependencyTree(); + dependencyTree.setIncrement(false); + return dependencyTree; + } File configFile = new File(baseDir + File.separator + CONFIG_NAME); // the config file no exists @@ -82,17 +93,14 @@ public static DependencyTree detect(String baseDir, boolean isIncrement) { } else { dependencyTree = Support.load(configFile); } - // if file no exists, and not increment build, delete the config file after build - if (fileNoExists && !isIncrement) { - configFile.delete(); - } - return dependencyTree; } public static void write(DependencyTree dependencyTree) { // do something when the dependency-tree format is changed dependent on the version - Support.writeFile(dependencyTree); + if (dependencyTree.isIncrement()) { + Support.writeFile(dependencyTree); + } } public String getSchema() { @@ -116,6 +124,14 @@ public void setConfig(String commitId, List dependencyTree) { this.dependencyTree = dependencyTree; } + public boolean isIncrement() { + return increment; + } + + public void setIncrement(boolean increment) { + this.increment = increment; + } + /** * Provide some utility methods */ diff --git a/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java b/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java index 862d79330..47c75b9b0 100644 --- a/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java @@ -170,22 +170,24 @@ default List getJavaParameterList(ProjectDocConfigBuilder buil } apiJavaParameter.setTypeValue(javaType.getValue()); String genericCanonicalName = javaType.getGenericCanonicalName(); - String fullTypeName = javaType.getGenericFullyQualifiedName(); + String fullyQualifiedName = javaType.getFullyQualifiedName(); + apiJavaParameter.setFullyQualifiedName(fullyQualifiedName); + String genericFullyQualifiedName = javaType.getGenericFullyQualifiedName(); String commentClass = paramTagMap.get(paramName); //ignore request params if (Objects.nonNull(commentClass) && commentClass.contains(IGNORE)) { continue; } - String rewriteClassName = getRewriteClassName(replacementMap, fullTypeName, commentClass); + String rewriteClassName = getRewriteClassName(replacementMap, genericFullyQualifiedName, commentClass); // rewrite class if (JavaClassValidateUtil.isClassName(rewriteClassName)) { genericCanonicalName = rewriteClassName; - fullTypeName = DocClassUtil.getSimpleName(rewriteClassName); + genericFullyQualifiedName = DocClassUtil.getSimpleName(rewriteClassName); } if (JavaClassValidateUtil.isMvcIgnoreParams(genericCanonicalName, builder.getApiConfig().getIgnoreRequestParams())) { continue; } - fullTypeName = DocClassUtil.rewriteRequestParam(fullTypeName); + genericFullyQualifiedName = DocClassUtil.rewriteRequestParam(genericFullyQualifiedName); genericCanonicalName = DocClassUtil.rewriteRequestParam(genericCanonicalName); List annotations = parameter.getAnnotations(); apiJavaParameter.setAnnotations(annotations); @@ -196,18 +198,18 @@ default List getJavaParameterList(ProjectDocConfigBuilder buil if (Objects.nonNull(builder.getApiConfig().getRequestBodyAdvice()) && Objects.isNull(javaMethod.getTagByName(IGNORE_REQUEST_BODY_ADVICE))) { String requestBodyAdvice = builder.getApiConfig().getRequestBodyAdvice().getClassName(); - fullTypeName = requestBodyAdvice; + genericFullyQualifiedName = requestBodyAdvice; genericCanonicalName = requestBodyAdvice + "<" + genericCanonicalName + ">"; } } } - if (JavaClassValidateUtil.isCollection(fullTypeName) || JavaClassValidateUtil.isArray(fullTypeName)) { + if (JavaClassValidateUtil.isCollection(genericFullyQualifiedName) || JavaClassValidateUtil.isArray(genericFullyQualifiedName)) { if (JavaClassValidateUtil.isCollection(genericCanonicalName)) { genericCanonicalName = genericCanonicalName + ""; } } apiJavaParameter.setGenericCanonicalName(genericCanonicalName); - apiJavaParameter.setFullyQualifiedName(fullTypeName); + apiJavaParameter.setGenericFullyQualifiedName(genericFullyQualifiedName); apiJavaParameterList.add(apiJavaParameter); } return apiJavaParameterList; diff --git a/src/main/java/com/ly/doc/template/IRestDocTemplate.java b/src/main/java/com/ly/doc/template/IRestDocTemplate.java index 05b58e981..262b1fe8c 100644 --- a/src/main/java/com/ly/doc/template/IRestDocTemplate.java +++ b/src/main/java/com/ly/doc/template/IRestDocTemplate.java @@ -275,11 +275,17 @@ default List handleTagsApiDoc(List apiDocList) { default List getClassAnnotations(JavaClass cls, FrameworkAnnotations frameworkAnnotations) { List annotationsList = new ArrayList<>(cls.getAnnotations()); - Map entryAnnotationMap = frameworkAnnotations.getEntryAnnotations(); - Map mappingAnnotationMap = frameworkAnnotations.getMappingAnnotations(); boolean flag = annotationsList.stream().anyMatch(item -> { String annotationName = item.getType().getValue(); String fullyName = item.getType().getFullyQualifiedName(); + Map entryAnnotationMap = frameworkAnnotations.getEntryAnnotations(); + if (Objects.isNull(entryAnnotationMap)) { + entryAnnotationMap = Collections.emptyMap(); + } + Map mappingAnnotationMap = frameworkAnnotations.getMappingAnnotations(); + if (Objects.isNull(mappingAnnotationMap)) { + mappingAnnotationMap = Collections.emptyMap(); + } return (entryAnnotationMap.containsKey(annotationName) || entryAnnotationMap.containsKey(fullyName))&& (mappingAnnotationMap.containsKey(annotationName)||mappingAnnotationMap.containsKey(fullyName)); }); @@ -548,14 +554,15 @@ default ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje String typeName = apiParameter.getGenericCanonicalName(); String simpleTypeName = apiParameter.getTypeValue(); String simpleName = simpleTypeName.toLowerCase(); - String fullTypeName = apiParameter.getFullyQualifiedName(); - if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(fullTypeName) && isStrict) { + String fullyQualifiedName = apiParameter.getFullyQualifiedName(); + String genericFullyQualifiedName = apiParameter.getGenericFullyQualifiedName(); + if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(fullyQualifiedName) && isStrict) { throw new RuntimeException("ERROR: Unable to find javadoc @param for actual param \"" + paramName + "\" in method " + javaMethod.getName() + " from " + className); } StringBuilder comment = new StringBuilder(this.paramCommentResolve(paramTagMap.get(paramName))); - JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(fullTypeName); + JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(genericFullyQualifiedName); String mockValue = JavaFieldUtil.createMockValue(paramsComments, paramName, typeName, simpleTypeName); List annotations = parameter.getAnnotations(); Set groupClasses = JavaClassUtil.getParamGroupJavaClass(annotations, builder.getJavaProjectBuilder()); @@ -601,7 +608,7 @@ default ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje // throw new RuntimeException("You have use @RequestBody Passing multiple variables for method " // + javaMethod.getName() + " in " + className + ",@RequestBody annotation could only bind one variables."); // } - mockValue = JsonBuildHelper.buildJson(fullTypeName, typeName, Boolean.FALSE, 0, new HashMap<>(), groupClasses, builder); + mockValue = JsonBuildHelper.buildJson(genericFullyQualifiedName, typeName, Boolean.FALSE, 0, new HashMap<>(), groupClasses, builder); requestBodyCounter++; isRequestBody = true; } @@ -628,7 +635,7 @@ default ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje } boolean queryParam = !isRequestBody && !isPathVariable; - if (JavaClassValidateUtil.isCollection(fullTypeName) || JavaClassValidateUtil.isArray(fullTypeName)) { + if (JavaClassValidateUtil.isCollection(fullyQualifiedName) || JavaClassValidateUtil.isArray(fullyQualifiedName)) { String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); String gicName = gicNameArr[0]; if (JavaClassValidateUtil.isArray(gicName)) { @@ -691,7 +698,7 @@ default ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje groupClasses, 0, Boolean.TRUE, null)); } } - } else if (JavaClassValidateUtil.isPrimitive(fullTypeName)) { + } else if (JavaClassValidateUtil.isPrimitive(fullyQualifiedName)) { ApiParam param = ApiParam.of() .setField(paramName) .setType(DocClassUtil.processTypeNameForParams(simpleName)) @@ -707,7 +714,7 @@ default ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje Map map = OpenApiSchemaUtil.primaryTypeSchema(simpleName); docJavaMethod.setRequestSchema(map); } - } else if (JavaClassValidateUtil.isMap(fullTypeName)) { + } else if (JavaClassValidateUtil.isMap(fullyQualifiedName)) { log.warning("When using smart-doc, it is not recommended to use Map to receive parameters, Check it in " + javaMethod.getDeclaringClass().getCanonicalName() + "#" + javaMethod.getName()); // is map without Gic @@ -831,10 +838,11 @@ default ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap for (DocJavaParameter apiParameter : parameterList) { JavaParameter parameter = apiParameter.getJavaParameter(); String paramName = parameter.getName(); - String typeName = apiParameter.getFullyQualifiedName(); + String genericFullyQualifiedName = apiParameter.getGenericFullyQualifiedName(); + String fullyQualifiedName = apiParameter.getFullyQualifiedName(); String gicTypeName = apiParameter.getGenericCanonicalName(); String simpleTypeName = apiParameter.getTypeValue(); - JavaClass javaClass = configBuilder.getJavaProjectBuilder().getClassByName(typeName); + JavaClass javaClass = configBuilder.getJavaProjectBuilder().getClassByName(genericFullyQualifiedName); String[] globGicName = DocClassUtil.getSimpleGicName(gicTypeName); String comment = this.paramCommentResolve(paramsComments.get(paramName)); String mockValue = JavaFieldUtil.createMockValue(paramsComments, paramName, gicTypeName, simpleTypeName); @@ -870,7 +878,7 @@ default ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap apiMethodDoc.setContentType(JSON_CONTENT_TYPE); } boolean isArrayOrCollection = false; - if (JavaClassValidateUtil.isArray(typeName) || JavaClassValidateUtil.isCollection(typeName)) { + if (JavaClassValidateUtil.isArray(genericFullyQualifiedName) || JavaClassValidateUtil.isCollection(fullyQualifiedName)) { simpleTypeName = globGicName[0]; isArrayOrCollection = true; } @@ -886,7 +894,7 @@ default ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap } requestExample.setJsonBody(mockValue).setJson(true); } else { - String json = JsonBuildHelper.buildJson(typeName, gicTypeName, Boolean.FALSE, 0, new HashMap<>(), groupClasses, + String json = JsonBuildHelper.buildJson(genericFullyQualifiedName, gicTypeName, Boolean.FALSE, 0, new HashMap<>(), groupClasses, configBuilder); requestExample.setJsonBody(JsonUtil.toPrettyFormat(json)).setJson(true); } @@ -913,7 +921,7 @@ default ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap if (JavaClassValidateUtil.isPrimitive(simpleTypeName)) { requestExample.addJsonBody(mockValue); } - if (JavaClassValidateUtil.isFile(typeName)) { + if (JavaClassValidateUtil.isFile(fullyQualifiedName)) { break; } // array and list @@ -931,7 +939,7 @@ default ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap FormData formData = new FormData(); formData.setKey(paramName); formData.setType("file"); - if (typeName.contains("[]") || typeName.endsWith(">")) { + if (genericFullyQualifiedName.contains("[]") || genericFullyQualifiedName.endsWith(">")) { comment = comment + "(array of file)"; formData.setType(DocGlobalConstants.PARAM_TYPE_FILE); formData.setHasItems(true); @@ -940,14 +948,14 @@ default ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap formData.setValue(mockValue); formData.setSrc(new ArrayList(0)); formDataList.add(formData); - } else if (JavaClassValidateUtil.isPrimitive(typeName) && !requestParam) { + } else if (JavaClassValidateUtil.isPrimitive(fullyQualifiedName) && !requestParam) { FormData formData = new FormData(); formData.setKey(paramName); formData.setDescription(comment); formData.setType("text"); formData.setValue(mockValue); formDataList.add(formData); - } else if (JavaClassValidateUtil.isArray(typeName) || JavaClassValidateUtil.isCollection(typeName)) { + } else if (JavaClassValidateUtil.isArray(fullyQualifiedName) || JavaClassValidateUtil.isCollection(fullyQualifiedName)) { String gicName = globGicName[0]; if (JavaClassValidateUtil.isArray(gicName)) { gicName = gicName.substring(0, gicName.indexOf("[")); diff --git a/src/main/java/com/ly/doc/template/JaxrsDocBuildTemplate.java b/src/main/java/com/ly/doc/template/JaxrsDocBuildTemplate.java index 1ddcf3f79..a0ca5cdcc 100644 --- a/src/main/java/com/ly/doc/template/JaxrsDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/JaxrsDocBuildTemplate.java @@ -348,9 +348,10 @@ private ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje String typeName = apiParameter.getGenericCanonicalName(); String simpleName = apiParameter.getTypeValue().toLowerCase(); - String fullTypeName = apiParameter.getFullyQualifiedName(); + String fullyQualifiedName = apiParameter.getFullyQualifiedName(); + String genericFullyQualifiedName = apiParameter.getGenericFullyQualifiedName(); String simpleTypeName = apiParameter.getTypeValue(); - if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(fullTypeName) && isStrict) { + if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(genericFullyQualifiedName) && isStrict) { throw new RuntimeException("ERROR: Unable to find javadoc @QueryParam for actual param \"" + paramName + "\" in method " + javaMethod.getName() + " from " + className); } @@ -359,7 +360,7 @@ private ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje paramName = StringUtil.camelToUnderline(paramName); } String mockValue = JavaFieldUtil.createMockValue(paramsComments, paramName, typeName, simpleTypeName); - JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(fullTypeName); + JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(genericFullyQualifiedName); List annotations = parameter.getAnnotations(); Set groupClasses = JavaClassUtil.getParamGroupJavaClass(annotations, builder.getJavaProjectBuilder()); @@ -398,7 +399,7 @@ private ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje boolean required = Boolean.parseBoolean(strRequired); boolean queryParam = !isRequestBody && !isPathVariable; - if (JavaClassValidateUtil.isCollection(fullTypeName) || JavaClassValidateUtil.isArray(fullTypeName)) { + if (JavaClassValidateUtil.isCollection(fullyQualifiedName) || JavaClassValidateUtil.isArray(fullyQualifiedName)) { String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); String gicName = gicNameArr[0]; if (JavaClassValidateUtil.isArray(gicName)) { @@ -441,7 +442,7 @@ private ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje "true", Boolean.FALSE, new HashMap<>(), builder, groupClasses, id, Boolean.FALSE, null); paramList.addAll(apiParamList); } - } else if (JavaClassValidateUtil.isPrimitive(fullTypeName)) { + } else if (JavaClassValidateUtil.isPrimitive(fullyQualifiedName)) { ApiParam param = ApiParam.of() .setField(paramName) .setType(DocClassUtil.processTypeNameForParams(simpleName)) @@ -453,7 +454,7 @@ private ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje .setRequired(required) .setVersion(DocGlobalConstants.DEFAULT_VERSION); paramList.add(param); - } else if (JavaClassValidateUtil.isMap(fullTypeName)) { + } else if (JavaClassValidateUtil.isMap(fullyQualifiedName)) { log.warning("When using smart-doc, it is not recommended to use Map to receive parameters, Check it in " + javaMethod.getDeclaringClass().getCanonicalName() + "#" + javaMethod.getName()); if (JavaClassValidateUtil.isMap(typeName)) { @@ -563,7 +564,8 @@ private ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap for (DocJavaParameter apiParameter : parameterList) { JavaParameter parameter = apiParameter.getJavaParameter(); String paramName = parameter.getName(); - String typeName = apiParameter.getFullyQualifiedName(); + String typeName = apiParameter.getGenericFullyQualifiedName(); + String fullyQualifiedName = apiParameter.getFullyQualifiedName(); String gicTypeName = apiParameter.getGenericCanonicalName(); String simpleTypeName = apiParameter.getTypeValue(); gicTypeName = DocClassUtil.rewriteRequestParam(gicTypeName); @@ -609,7 +611,7 @@ private ApiRequestExample buildReqJson(DocJavaMethod javaMethod, ApiMethodDoc ap formData.setType("text"); formData.setValue(mockValue); formDataList.add(formData); - } else if (JavaClassValidateUtil.isArray(typeName) || JavaClassValidateUtil.isCollection(typeName)) { + } else if (JavaClassValidateUtil.isArray(fullyQualifiedName) || JavaClassValidateUtil.isCollection(fullyQualifiedName)) { String gicName = globGicName[0]; if (JavaClassValidateUtil.isArray(gicName)) { gicName = gicName.substring(0, gicName.indexOf("["));