Skip to content

Commit

Permalink
Merge pull request #729 from shalousun/master
Browse files Browse the repository at this point in the history 
Fix JAX-RS documentation generation bug.
  • Loading branch information
@shalousun
shalousun authored Feb 5, 2024
2 parents 936ba6f + a02b543 commit 3c276b6
Show file tree
Hide file tree
Showing 6 changed files with 80 additions and 38 deletions.
3 changes: 3 additions & 0 deletions src/main/java/com/ly/doc/helper/DocBuildHelper.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,9 @@ private void writeDependencyTree(List<ApiDependency> dependencyTree) {
}

private List<ApiDependency> mergeDependencyTree(List<ApiDependency> newDependencyTree) {
if (Objects.isNull(this.dependencyTree.getDependencyTree())) {
return new ArrayList<>();
}
List<ApiDependency> oldDependencyTree = new ArrayList<>(this.dependencyTree.getDependencyTree());

// remove the deleted or deprecated dependencies
Expand Down
11 changes: 11 additions & 0 deletions src/main/java/com/ly/doc/model/DocJavaParameter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@ public class DocJavaParameter {

private String genericCanonicalName;

private String genericFullyQualifiedName;


private String fullyQualifiedName;

private String typeValue;
Expand All @@ -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;
}
Expand Down
28 changes: 22 additions & 6 deletions src/main/java/com/ly/doc/model/dependency/DependencyTree.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down Expand Up @@ -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
Expand All @@ -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() {
Expand All @@ -116,6 +124,14 @@ public void setConfig(String commitId, List<ApiDependency> dependencyTree) {
this.dependencyTree = dependencyTree;
}

public boolean isIncrement() {
return increment;
}

public void setIncrement(boolean increment) {
this.increment = increment;
}

/**
* Provide some utility methods
*/
Expand Down
16 changes: 9 additions & 7 deletions src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -170,22 +170,24 @@ default List<DocJavaParameter> 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<JavaAnnotation> annotations = parameter.getAnnotations();
apiJavaParameter.setAnnotations(annotations);
Expand All @@ -196,18 +198,18 @@ default List<DocJavaParameter> 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 + "<T>";
}
}
apiJavaParameter.setGenericCanonicalName(genericCanonicalName);
apiJavaParameter.setFullyQualifiedName(fullTypeName);
apiJavaParameter.setGenericFullyQualifiedName(genericFullyQualifiedName);
apiJavaParameterList.add(apiJavaParameter);
}
return apiJavaParameterList;
Expand Down
42 changes: 25 additions & 17 deletions src/main/java/com/ly/doc/template/IRestDocTemplate.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -275,11 +275,17 @@ default List<ApiDoc> handleTagsApiDoc(List<ApiDoc> apiDocList) {

default List<JavaAnnotation> getClassAnnotations(JavaClass cls, FrameworkAnnotations frameworkAnnotations) {
List<JavaAnnotation> annotationsList = new ArrayList<>(cls.getAnnotations());
Map<String, EntryAnnotation> entryAnnotationMap = frameworkAnnotations.getEntryAnnotations();
Map<String, MappingAnnotation> mappingAnnotationMap = frameworkAnnotations.getMappingAnnotations();
boolean flag = annotationsList.stream().anyMatch(item -> {
String annotationName = item.getType().getValue();
String fullyName = item.getType().getFullyQualifiedName();
Map<String, EntryAnnotation> entryAnnotationMap = frameworkAnnotations.getEntryAnnotations();
if (Objects.isNull(entryAnnotationMap)) {
entryAnnotationMap = Collections.emptyMap();
}
Map<String, MappingAnnotation> mappingAnnotationMap = frameworkAnnotations.getMappingAnnotations();
if (Objects.isNull(mappingAnnotationMap)) {
mappingAnnotationMap = Collections.emptyMap();
}
return (entryAnnotationMap.containsKey(annotationName) || entryAnnotationMap.containsKey(fullyName))&&
(mappingAnnotationMap.containsKey(annotationName)||mappingAnnotationMap.containsKey(fullyName));
});
Expand Down Expand Up @@ -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<JavaAnnotation> annotations = parameter.getAnnotations();
Set<String> groupClasses = JavaClassUtil.getParamGroupJavaClass(annotations, builder.getJavaProjectBuilder());
Expand Down Expand Up @@ -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;
}
Expand All @@ -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)) {
Expand Down Expand Up @@ -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))
Expand All @@ -707,7 +714,7 @@ default ApiMethodReqParam requestParams(final DocJavaMethod docJavaMethod, Proje
Map<String, Object> 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
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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;
}
Expand All @@ -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);
}
Expand All @@ -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
Expand All @@ -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);
Expand All @@ -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("["));
Expand Down
Loading

0 comments on commit 3c276b6

Please sign in to comment.