Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix JAX-RS documentation generation bug. #729

Merged
merged 1 commit into from
Feb 5, 2024
Merged

Fix JAX-RS documentation generation bug. #729

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/main/java/com/ly/doc/helper/DocBuildHelper.java
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading