diff --git a/src/main/java/com/ly/doc/model/RpcJavaMethod.java b/src/main/java/com/ly/doc/model/RpcJavaMethod.java index f896e211..b0059620 100644 --- a/src/main/java/com/ly/doc/model/RpcJavaMethod.java +++ b/src/main/java/com/ly/doc/model/RpcJavaMethod.java @@ -20,261 +20,11 @@ */ package com.ly.doc.model; -import com.ly.doc.utils.ParamUtil; -import com.thoughtworks.qdox.model.JavaClass; -import com.thoughtworks.qdox.model.JavaMethod; -import com.thoughtworks.qdox.model.JavaType; - -import java.util.List; -import java.util.Map; - /** * for rpc + * * @author yu 2020/1/29. */ -public class RpcJavaMethod implements IMethod { - - /** - * java method - */ - private JavaMethod javaMethod; - - /** - * methodId handled by md5 - */ - private String methodId; - - /** - * method name - */ - private String name; - - /** - * method order - */ - private int order; - - - /** - * method description - */ - private String desc; - - /** - * method definition - */ - private String methodDefinition; - - /** - * escape method definition - */ - private String escapeMethodDefinition; - - /** - * detailed introduction of the method - */ - private String detail; - - /** - * method describe - */ - private String throwsInfo; - - /** - * return class Info - */ - private String returnClassInfo; - - /** - * http request params - */ - private List requestParams; - - /** - * http request author - */ - private String author; - - /** - * http response params - */ - private List responseParams; - - /** - * method deprecated - */ - private boolean deprecated; - - private Map actualTypesMap; - - - private String version; - - public String getVersion() { - return version; - } - - public RpcJavaMethod setVersion(String version) { - this.version = version; - return this; - } - - public static RpcJavaMethod builder() { - return new RpcJavaMethod(); - } - - public JavaMethod getJavaMethod() { - return javaMethod; - } - - public RpcJavaMethod setJavaMethod(JavaMethod javaMethod) { - this.javaMethod = javaMethod; - return this; - } - - public String getMethodId() { - return methodId; - } - - public RpcJavaMethod setMethodId(String methodId) { - this.methodId = methodId; - return this; - } - - public String getName() { - return name; - } - - public RpcJavaMethod setName(String name) { - this.name = name; - return this; - } - - public int getOrder() { - return order; - } - - public RpcJavaMethod setOrder(int order) { - this.order = order; - return this; - } - - public String getDesc() { - return desc; - } - - public RpcJavaMethod setDesc(String desc) { - this.desc = desc; - return this; - } - - public String getDetail() { - return detail; - } - - public RpcJavaMethod setDetail(String detail) { - this.detail = detail; - return this; - } - - public String getThrowsInfo() { - return throwsInfo; - } - - public RpcJavaMethod setThrowsInfo(String throwsInfo) { - this.throwsInfo = throwsInfo; - return this; - } - - public String getReturnClassInfo() { - return returnClassInfo; - } - - public RpcJavaMethod setReturnClassInfo(String returnClassInfo) { - this.returnClassInfo = returnClassInfo; - return this; - } - - public String getAuthor() { - return author; - } - - public RpcJavaMethod setAuthor(String author) { - this.author = author; - return this; - } - - public List getResponseParams() { - return responseParams; - } - - public RpcJavaMethod setResponseParams(List responseParams) { - this.responseParams = responseParams; - return this; - } - - public boolean isDeprecated() { - return deprecated; - } - - public RpcJavaMethod setDeprecated(boolean deprecated) { - this.deprecated = deprecated; - return this; - } - - public List getRequestParams() { - return requestParams; - } - - public RpcJavaMethod setRequestParams(List requestParams) { - this.requestParams = requestParams; - return this; - } - - public String getMethodDefinition() { - return methodDefinition; - } - - public RpcJavaMethod setMethodDefinition(String methodDefinition) { - this.methodDefinition = methodDefinition; - return this; - } - - public String getEscapeMethodDefinition() { - return escapeMethodDefinition; - } - - public RpcJavaMethod setEscapeMethodDefinition(String escapeMethodDefinition) { - this.escapeMethodDefinition = escapeMethodDefinition; - return this; - } - - public Map getActualTypesMap() { - return actualTypesMap; - } - - public RpcJavaMethod setActualTypesMap(Map actualTypesMap) { - this.actualTypesMap = actualTypesMap; - return this; - } - - @Override - public JavaClass getDeclaringClass() { - return this.javaMethod.getDeclaringClass(); - } - - @Override - public String getMethodName() { - return this.name; - } - - @Override - public List getArgsClasses() { - return ParamUtil.extractQualifiedName(this.requestParams); - } +public class RpcJavaMethod extends JavadocJavaMethod { - @Override - public List getReturnClasses() { - return ParamUtil.extractQualifiedName(this.responseParams); - } } diff --git a/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java b/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java index 9c0f7ceb..ac13a5e5 100644 --- a/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java +++ b/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java @@ -21,6 +21,7 @@ package com.ly.doc.template; import com.ly.doc.builder.ProjectDocConfigBuilder; +import com.ly.doc.constants.DocTags; import com.ly.doc.constants.TornaConstants; import com.ly.doc.helper.DocBuildHelper; import com.ly.doc.model.ApiConfig; @@ -34,6 +35,7 @@ import com.power.common.util.CollectionUtil; import com.power.common.util.StringUtil; import com.thoughtworks.qdox.JavaProjectBuilder; +import com.thoughtworks.qdox.model.DocletTag; import com.thoughtworks.qdox.model.JavaClass; import java.util.*; @@ -196,6 +198,26 @@ default boolean isEntryPoint(JavaProjectBuilder javaProjectBuilder, String javaC return isEntryPoint(javaClass, registeredAnnotations()); } + default boolean skipClass( ApiConfig apiConfig ,JavaClass javaClass, FrameworkAnnotations frameworkAnnotations) { + if (StringUtil.isNotEmpty(apiConfig.getPackageFilters())) { + // from smart config + if (!DocUtil.isMatch(apiConfig.getPackageFilters(), javaClass)) { + return true; + } + } + if (StringUtil.isNotEmpty(apiConfig.getPackageExcludeFilters())) { + if (DocUtil.isMatch(apiConfig.getPackageExcludeFilters(), javaClass)) { + return true; + } + } + // from tag + DocletTag ignoreTag = javaClass.getTagByName(DocTags.IGNORE); + if (!isEntryPoint(javaClass, frameworkAnnotations) || Objects.nonNull(ignoreTag)) { + return true; + } + return false; + } + /** * is entry point * diff --git a/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java b/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java index 4c4f4461..a78a7825 100644 --- a/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java +++ b/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java @@ -20,25 +20,30 @@ */ package com.ly.doc.template; +import com.ly.doc.builder.ProjectDocConfigBuilder; import com.ly.doc.constants.DocAnnotationConstants; +import com.ly.doc.constants.DocGlobalConstants; import com.ly.doc.constants.DocTags; +import com.ly.doc.helper.ParamsBuildHelper; import com.ly.doc.model.ApiConfig; +import com.ly.doc.model.ApiParam; +import com.ly.doc.model.DocJavaMethod; import com.ly.doc.model.JavadocJavaMethod; -import com.ly.doc.utils.DocClassUtil; -import com.ly.doc.utils.DocUtil; -import com.ly.doc.utils.JavaClassUtil; +import com.ly.doc.utils.*; import com.power.common.util.StringUtil; import com.thoughtworks.qdox.model.*; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; +import java.util.*; +import java.util.concurrent.atomic.AtomicInteger; import static com.ly.doc.constants.DocTags.DEPRECATED; +import static com.ly.doc.constants.DocTags.IGNORE; public interface IJavadocDocTemplate extends IBaseDocBuildTemplate { + + boolean addMethodModifiers(); + default JavadocJavaMethod convertToJavadocJavaMethod(ApiConfig apiConfig, JavaMethod method, Map actualTypesMap) { JavaClass cls = method.getDeclaringClass(); JavadocJavaMethod javadocJavaMethod = new JavadocJavaMethod(); @@ -82,8 +87,10 @@ default JavadocJavaMethod convertToJavadocJavaMethod(ApiConfig apiConfig, JavaMe default String methodDefinition(JavaMethod method, Map actualTypesMap) { StringBuilder methodBuilder = new StringBuilder(); - // append method modifiers - method.getModifiers().forEach(item -> methodBuilder.append(item).append(" ")); + if (addMethodModifiers()) { + // append method modifiers + method.getModifiers().forEach(item -> methodBuilder.append(item).append(" ")); + } JavaType returnType = method.getReturnType(); String simpleReturn = replaceTypeName(returnType.getCanonicalName(), actualTypesMap, Boolean.TRUE); String returnClass = replaceTypeName(returnType.getGenericCanonicalName(), actualTypesMap, Boolean.TRUE); @@ -119,7 +126,7 @@ default String methodDefinition(JavaMethod method, Map actualT return methodBuilder.toString(); } - default List getParentsClassMethods(ApiConfig apiConfig, JavaClass cls) { + default List getParentsClassMethods(ApiConfig apiConfig, JavaClass cls) { List docJavaMethods = new ArrayList<>(); JavaClass parentClass = cls.getSuperJavaClass(); if (Objects.nonNull(parentClass) && !"Object".equals(parentClass.getSimpleName())) { @@ -133,7 +140,7 @@ default List getParentsClassMethods(ApiConfig apiConfig, Java return docJavaMethods; } - default List getInterfaceMethods(ApiConfig apiConfig, JavaClass cls) { + default List getInterfaceMethods(ApiConfig apiConfig, JavaClass cls) { List docJavaMethods = new ArrayList<>(); for (JavaClass javaInterface : cls.getInterfaces()) { Map actualTypesMap = JavaClassUtil.getActualTypesMap(javaInterface); @@ -161,4 +168,154 @@ default String replaceTypeName(String type, Map actualTypesMap } return type; } + + default List requestParams(final JavaMethod javaMethod, + ProjectDocConfigBuilder builder, + AtomicInteger atomicInteger, + Map actualTypesMap) { + boolean isStrict = builder.getApiConfig().isStrict(); + boolean isShowJavaType = builder.getApiConfig().getShowJavaType(); + boolean isShowValidation = builder.getApiConfig().isShowValidation(); + String className = javaMethod.getDeclaringClass().getCanonicalName(); + Map paramTagMap = DocUtil.getCommentsByTag(javaMethod, DocTags.PARAM, className); + List parameterList = javaMethod.getParameters(); + if (parameterList.isEmpty()) { + return null; + } + ClassLoader classLoader = builder.getApiConfig().getClassLoader(); + List paramList = new ArrayList<>(); + for (JavaParameter parameter : parameterList) { + boolean required = false; + String paramName = parameter.getName(); + String typeName = replaceTypeName(parameter.getType().getGenericCanonicalName(), actualTypesMap, Boolean.FALSE); + String simpleName = replaceTypeName(parameter.getType().getValue(), actualTypesMap, Boolean.FALSE).toLowerCase(); + String fullTypeName = replaceTypeName(parameter.getType().getFullyQualifiedName(), actualTypesMap, Boolean.FALSE); + String paramPre = paramName + "."; + if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(fullTypeName) && 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))); + String mockValue = JavaFieldUtil.createMockValue(paramTagMap, paramName, typeName, typeName); + JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(fullTypeName); + List annotations = parameter.getAnnotations(); + for (JavaAnnotation a : annotations) { + if (JavaClassValidateUtil.isJSR303Required(a.getType().getValue())) { + required = true; + } + } + comment.append(JavaFieldUtil.getJsrComment(isShowValidation, classLoader, annotations)); + Set groupClasses = JavaClassUtil.getParamGroupJavaClass(annotations, builder.getJavaProjectBuilder()); + if (JavaClassValidateUtil.isCollection(fullTypeName) || JavaClassValidateUtil.isArray(fullTypeName)) { + if (JavaClassValidateUtil.isCollection(typeName)) { + typeName = typeName + ""; + } + String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); + String gicName = gicNameArr[0]; + if (JavaClassValidateUtil.isArray(gicName)) { + gicName = gicName.substring(0, gicName.indexOf("[")); + } + if (JavaClassValidateUtil.isPrimitive(gicName)) { + String processedType = isShowJavaType ? + JavaClassUtil.getClassSimpleName(typeName) : DocClassUtil.processTypeNameForParams(simpleName); + ApiParam param = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName) + .setDesc(comment + " (children type : " + gicName + ")") + .setRequired(required) + .setType(processedType); + paramList.add(param); + } else { + paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], paramPre, 0, "true", + Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); + } + } else if (JavaClassValidateUtil.isPrimitive(fullTypeName)) { + ApiParam param = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName) + .setType(JavaClassUtil.getClassSimpleName(typeName)) + .setDesc(comment.toString()) + .setRequired(required) + .setMaxLength(JavaFieldUtil.getParamMaxLength(parameter.getAnnotations())) + .setValue(mockValue) + .setVersion(DocGlobalConstants.DEFAULT_VERSION); + paramList.add(param); + } else if (JavaClassValidateUtil.isMap(fullTypeName)) { + if (JavaClassValidateUtil.isMap(typeName)) { + ApiParam apiParam = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName).setType(typeName) + .setDesc(comment.toString()).setRequired(required).setVersion(DocGlobalConstants.DEFAULT_VERSION); + paramList.add(apiParam); + continue; + } + String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); + paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], paramPre, 0, "true", + Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); + } else if (javaClass.isEnum()) { + ApiParam param = ApiParam.of() + .setId(atomicInteger.incrementAndGet()) + .setField(paramName) + .setType(DocGlobalConstants.PARAM_TYPE_ENUM) + .setRequired(required) + .setDesc(comment.toString()) + .setVersion(DocGlobalConstants.DEFAULT_VERSION); + paramList.add(param); + } else { + paramList.addAll(ParamsBuildHelper.buildParams(typeName, paramPre, 0, "true", + Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); + } + } + return paramList; + } + + default List buildServiceMethod(final JavaClass cls, ApiConfig apiConfig, ProjectDocConfigBuilder projectBuilder) { + String clazName = cls.getCanonicalName(); + List methods = cls.getMethods(); + List methodDocList = new ArrayList<>(methods.size()); + + Set filterMethods = DocUtil.findFilterMethods(clazName); + boolean needAllMethods = filterMethods.contains(DocGlobalConstants.DEFAULT_FILTER_METHOD); + + for (JavaMethod method : methods) { + if (method.isPrivate()) { + continue; + } + if (Objects.nonNull(method.getTagByName(IGNORE))) { + continue; + } + if (StringUtil.isEmpty(method.getComment()) && apiConfig.isStrict()) { + throw new RuntimeException("Unable to find comment for method " + method.getName() + " in " + cls.getCanonicalName()); + } + if (needAllMethods || filterMethods.contains(method.getName())) { + JavadocJavaMethod apiMethodDoc = convertToJavadocJavaMethod(apiConfig, method, null); + methodDocList.add(apiMethodDoc); + } + + + } + // add parent class methods + methodDocList.addAll(getParentsClassMethods(apiConfig, cls)); + if (cls.isInterface() || cls.isAbstract()) { + methodDocList.addAll(getInterfaceMethods(apiConfig,cls)); + } + + int methodOrder = 0; + List javadocJavaMethods = new ArrayList<>(methodDocList.size()); + for (JavadocJavaMethod method : methodDocList) { + methodOrder++; + method.setOrder(methodOrder); + String methodUid = DocUtil.generateId(clazName + method.getName() + methodOrder); + method.setMethodId(methodUid); + // build request params + List requestParams = requestParams(method.getJavaMethod(), projectBuilder, + new AtomicInteger(0), method.getActualTypesMap()); + // build response params + List responseParams = buildReturnApiParams(DocJavaMethod.builder().setJavaMethod(method.getJavaMethod()) + .setActualTypesMap(method.getActualTypesMap()), projectBuilder); + if (apiConfig.isParamsDataToTree()) { + method.setRequestParams(ApiParamTreeUtil.apiParamToTree(requestParams)); + method.setResponseParams(ApiParamTreeUtil.apiParamToTree(responseParams)); + } else { + method.setRequestParams(requestParams); + method.setResponseParams(responseParams); + } + javadocJavaMethods.add(method); + } + return javadocJavaMethods; + } } diff --git a/src/main/java/com/ly/doc/template/IRestDocTemplate.java b/src/main/java/com/ly/doc/template/IRestDocTemplate.java index a17f0225..3bddbe5c 100644 --- a/src/main/java/com/ly/doc/template/IRestDocTemplate.java +++ b/src/main/java/com/ly/doc/template/IRestDocTemplate.java @@ -86,6 +86,7 @@ default List processApiData(ProjectDocConfigBuilder projectBuilder, Fram if (!isEntryPoint(cls, frameworkAnnotations) || Objects.nonNull(ignoreTag)) { continue; } + String strOrder = JavaClassUtil.getClassTagsValue(cls, DocTags.ORDER, Boolean.TRUE); order++; if (ValidateUtil.isNonNegativeInteger(strOrder)) { diff --git a/src/main/java/com/ly/doc/template/IRpcDocTemplate.java b/src/main/java/com/ly/doc/template/IRpcDocTemplate.java index 546ea170..8c1ca809 100644 --- a/src/main/java/com/ly/doc/template/IRpcDocTemplate.java +++ b/src/main/java/com/ly/doc/template/IRpcDocTemplate.java @@ -20,145 +20,11 @@ */ package com.ly.doc.template; -import com.ly.doc.constants.DocAnnotationConstants; -import com.ly.doc.model.ApiConfig; -import com.ly.doc.model.RpcJavaMethod; -import com.ly.doc.utils.DocUtil; -import com.ly.doc.utils.JavaClassUtil; -import com.power.common.util.StringUtil; -import com.ly.doc.constants.DocTags; -import com.ly.doc.utils.DocClassUtil; -import com.thoughtworks.qdox.model.*; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; - -import static com.ly.doc.constants.DocTags.DEPRECATED; /** * @author yu 2022/10/16. */ -public interface IRpcDocTemplate extends IBaseDocBuildTemplate { - - default RpcJavaMethod convertToRpcJavaMethod(ApiConfig apiConfig, JavaMethod method, Map actualTypesMap) { - JavaClass cls = method.getDeclaringClass(); - RpcJavaMethod rpcJavaMethod = new RpcJavaMethod(); - rpcJavaMethod.setJavaMethod(method); - rpcJavaMethod.setName(method.getName()); - rpcJavaMethod.setActualTypesMap(actualTypesMap); - String methodDefine = methodDefinition(method, actualTypesMap); - String scapeMethod = methodDefine.replaceAll("<", "<"); - scapeMethod = scapeMethod.replaceAll(">", ">"); - - rpcJavaMethod.setMethodDefinition(methodDefine); - rpcJavaMethod.setEscapeMethodDefinition(scapeMethod); - rpcJavaMethod.setDesc(DocUtil.getEscapeAndCleanComment(method.getComment())); - // set detail - String apiNoteValue = DocUtil.getNormalTagComments(method, DocTags.API_NOTE, cls.getName()); - if (StringUtil.isEmpty(apiNoteValue)) { - apiNoteValue = method.getComment(); - } - String version = DocUtil.getNormalTagComments(method, DocTags.SINCE, cls.getName()); - rpcJavaMethod.setVersion(version); - rpcJavaMethod.setDetail(apiNoteValue != null ? apiNoteValue : ""); - // set author - String authorValue = DocUtil.getNormalTagComments(method, DocTags.AUTHOR, cls.getName()); - if (apiConfig.isShowAuthor() && StringUtil.isNotEmpty(authorValue)) { - rpcJavaMethod.setAuthor(authorValue); - } - - //Deprecated - List annotations = method.getAnnotations(); - for (JavaAnnotation annotation : annotations) { - String annotationName = annotation.getType().getName(); - if (DocAnnotationConstants.DEPRECATED.equals(annotationName)) { - rpcJavaMethod.setDeprecated(true); - } - } - if (Objects.nonNull(method.getTagByName(DEPRECATED))) { - rpcJavaMethod.setDeprecated(true); - } - return rpcJavaMethod; - } - - default String methodDefinition(JavaMethod method, Map actualTypesMap) { - StringBuilder methodBuilder = new StringBuilder(); - JavaType returnType = method.getReturnType(); - String simpleReturn = replaceTypeName(returnType.getCanonicalName(), actualTypesMap, Boolean.TRUE); - String returnClass = replaceTypeName(returnType.getGenericCanonicalName(), actualTypesMap, Boolean.TRUE); - returnClass = returnClass.replace(simpleReturn, JavaClassUtil.getClassSimpleName(simpleReturn)); - String[] arrays = DocClassUtil.getSimpleGicName(returnClass); - for (String str : arrays) { - if (str.contains("[")) { - str = str.substring(0, str.indexOf("[")); - } - String[] generics = str.split("[<,]"); - for (String generic : generics) { - if (generic.contains("extends")) { - String className = generic.substring(generic.lastIndexOf(" ") + 1); - returnClass = returnClass.replace(className, JavaClassUtil.getClassSimpleName(className)); - } - if (generic.length() != 1 && !generic.contains("extends")) { - returnClass = returnClass.replaceAll(generic, JavaClassUtil.getClassSimpleName(generic)); - } - - } - } - methodBuilder.append(returnClass).append(" "); - List params = new ArrayList<>(); - List parameters = method.getParameters(); - for (JavaParameter parameter : parameters) { - String typeName = replaceTypeName(parameter.getType().getGenericValue(), actualTypesMap, Boolean.TRUE); - params.add(typeName + " " + parameter.getName()); - } - methodBuilder.append(method.getName()).append("(") - .append(String.join(", ", params)).append(")"); - return methodBuilder.toString(); - } - - default List getParentsClassMethods(ApiConfig apiConfig, JavaClass cls) { - List docJavaMethods = new ArrayList<>(); - JavaClass parentClass = cls.getSuperJavaClass(); - if (Objects.nonNull(parentClass) && !"Object".equals(parentClass.getSimpleName())) { - Map actualTypesMap = JavaClassUtil.getActualTypesMap(parentClass); - List parentMethodList = parentClass.getMethods(); - for (JavaMethod method : parentMethodList) { - docJavaMethods.add(convertToRpcJavaMethod(apiConfig, method, actualTypesMap)); - } - docJavaMethods.addAll(getParentsClassMethods(apiConfig, parentClass)); - } - return docJavaMethods; - } - - default List getInterfaceMethods(ApiConfig apiConfig, JavaClass cls) { - List docJavaMethods = new ArrayList<>(); - for (JavaClass javaInterface : cls.getInterfaces()) { - Map actualTypesMap = JavaClassUtil.getActualTypesMap(javaInterface); - List interfaceMethodList = javaInterface.getMethods(); - for (JavaMethod method : interfaceMethodList) { - docJavaMethods.add(convertToRpcJavaMethod(apiConfig, method, actualTypesMap)); - } - docJavaMethods.addAll(getInterfaceMethods(apiConfig, javaInterface)); - } - return docJavaMethods; - } - - default String replaceTypeName(String type, Map actualTypesMap, boolean simple) { - if (Objects.isNull(actualTypesMap)) { - return type; - } +public interface IRpcDocTemplate extends IJavadocDocTemplate { - for (Map.Entry entry : actualTypesMap.entrySet()) { - if (type.contains(entry.getKey())) { - if (simple) { - return type.replace(entry.getKey(), entry.getValue().getGenericValue()); - } else { - return type.replace(entry.getKey(), entry.getValue().getGenericFullyQualifiedName()); - } - } - } - return type; - } } diff --git a/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java b/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java index 03d8ea6f..89415ab5 100644 --- a/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java @@ -45,6 +45,11 @@ public class JavadocDocBuildTemplate implements IDocBuildTemplate */ private final AtomicInteger atomicInteger = new AtomicInteger(1); + @Override + public boolean addMethodModifiers() { + return true; + } + @Override public List renderApi(ProjectDocConfigBuilder projectBuilder, Collection candidateClasses) { ApiConfig apiConfig = projectBuilder.getApiConfig(); @@ -52,14 +57,7 @@ public List renderApi(ProjectDocConfigBuilder projectBuilder, Col int order = 0; boolean setCustomOrder = false; for (JavaClass cls : candidateClasses) { - if (StringUtil.isNotEmpty(apiConfig.getPackageFilters())) { - // check package - if (!DocUtil.isMatch(apiConfig.getPackageFilters(), cls)) { - continue; - } - } - DocletTag ignoreTag = cls.getTagByName(DocTags.IGNORE); - if (!isEntryPoint(cls, null) || Objects.nonNull(ignoreTag)) { + if (skipClass(apiConfig, cls, null)) { continue; } String strOrder = JavaClassUtil.getClassTagsValue(cls, DocTags.ORDER, Boolean.TRUE); @@ -68,7 +66,7 @@ public List renderApi(ProjectDocConfigBuilder projectBuilder, Col order = Integer.parseInt(strOrder); setCustomOrder = true; } - List apiMethodDocs = buildServiceMethod(cls, apiConfig, projectBuilder); + List apiMethodDocs = (List) buildServiceMethod(cls, apiConfig, projectBuilder); this.handleJavaApiDoc(cls, apiDocList, apiMethodDocs, order, projectBuilder); } // sort @@ -93,155 +91,6 @@ public boolean ignoreReturnObject(String typeName, List ignoreParams) { return false; } - private List buildServiceMethod(final JavaClass cls, ApiConfig apiConfig, ProjectDocConfigBuilder projectBuilder) { - String clazName = cls.getCanonicalName(); - List methods = cls.getMethods(); - List methodDocList = new ArrayList<>(methods.size()); - - Set filterMethods = DocUtil.findFilterMethods(clazName); - boolean needAllMethods = filterMethods.contains(DocGlobalConstants.DEFAULT_FILTER_METHOD); - - for (JavaMethod method : methods) { - if (method.isPrivate()) { - continue; - } - if (Objects.nonNull(method.getTagByName(IGNORE))) { - continue; - } - if (StringUtil.isEmpty(method.getComment()) && apiConfig.isStrict()) { - throw new RuntimeException("Unable to find comment for method " + method.getName() + " in " + cls.getCanonicalName()); - } - if (needAllMethods || filterMethods.contains(method.getName())) { - JavadocJavaMethod apiMethodDoc = convertToJavadocJavaMethod(apiConfig, method, null); - methodDocList.add(apiMethodDoc); - } - - - } - // add parent class methods - methodDocList.addAll(getParentsClassMethods(apiConfig, cls)); - if (cls.isInterface() || cls.isAbstract()) { - methodDocList.addAll(getInterfaceMethods(apiConfig,cls)); - } - - int methodOrder = 0; - List javadocJavaMethods = new ArrayList<>(methodDocList.size()); - for (JavadocJavaMethod method : methodDocList) { - methodOrder++; - method.setOrder(methodOrder); - String methodUid = DocUtil.generateId(clazName + method.getName() + methodOrder); - method.setMethodId(methodUid); - // build request params - List requestParams = requestParams(method.getJavaMethod(), projectBuilder, - new AtomicInteger(0), method.getActualTypesMap()); - // build response params - List responseParams = buildReturnApiParams(DocJavaMethod.builder().setJavaMethod(method.getJavaMethod()) - .setActualTypesMap(method.getActualTypesMap()), projectBuilder); - if (apiConfig.isParamsDataToTree()) { - method.setRequestParams(ApiParamTreeUtil.apiParamToTree(requestParams)); - method.setResponseParams(ApiParamTreeUtil.apiParamToTree(responseParams)); - } else { - method.setRequestParams(requestParams); - method.setResponseParams(responseParams); - } - javadocJavaMethods.add(method); - } - return javadocJavaMethods; - } - - private List requestParams(final JavaMethod javaMethod, - ProjectDocConfigBuilder builder, - AtomicInteger atomicInteger, - Map actualTypesMap) { - boolean isStrict = builder.getApiConfig().isStrict(); - boolean isShowJavaType = builder.getApiConfig().getShowJavaType(); - boolean isShowValidation = builder.getApiConfig().isShowValidation(); - String className = javaMethod.getDeclaringClass().getCanonicalName(); - Map paramTagMap = DocUtil.getCommentsByTag(javaMethod, DocTags.PARAM, className); - List parameterList = javaMethod.getParameters(); - if (parameterList.isEmpty()) { - return null; - } - ClassLoader classLoader = builder.getApiConfig().getClassLoader(); - List paramList = new ArrayList<>(); - for (JavaParameter parameter : parameterList) { - boolean required = false; - String paramName = parameter.getName(); - String typeName = replaceTypeName(parameter.getType().getGenericCanonicalName(), actualTypesMap, Boolean.FALSE); - String simpleName = replaceTypeName(parameter.getType().getValue(), actualTypesMap, Boolean.FALSE).toLowerCase(); - String fullTypeName = replaceTypeName(parameter.getType().getFullyQualifiedName(), actualTypesMap, Boolean.FALSE); - String paramPre = paramName + "."; - if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(fullTypeName) && 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))); - String mockValue = JavaFieldUtil.createMockValue(paramTagMap, paramName, typeName, typeName); - JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(fullTypeName); - List annotations = parameter.getAnnotations(); - for (JavaAnnotation a : annotations) { - if (JavaClassValidateUtil.isJSR303Required(a.getType().getValue())) { - required = true; - } - } - comment.append(JavaFieldUtil.getJsrComment(isShowValidation, classLoader, annotations)); - Set groupClasses = JavaClassUtil.getParamGroupJavaClass(annotations, builder.getJavaProjectBuilder()); - if (JavaClassValidateUtil.isCollection(fullTypeName) || JavaClassValidateUtil.isArray(fullTypeName)) { - if (JavaClassValidateUtil.isCollection(typeName)) { - typeName = typeName + ""; - } - String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); - String gicName = gicNameArr[0]; - if (JavaClassValidateUtil.isArray(gicName)) { - gicName = gicName.substring(0, gicName.indexOf("[")); - } - if (JavaClassValidateUtil.isPrimitive(gicName)) { - String processedType = isShowJavaType ? - JavaClassUtil.getClassSimpleName(typeName) : DocClassUtil.processTypeNameForParams(simpleName); - ApiParam param = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName) - .setDesc(comment + " (children type : " + gicName + ")") - .setRequired(required) - .setType(processedType); - paramList.add(param); - } else { - paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], paramPre, 0, "true", - Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); - } - } else if (JavaClassValidateUtil.isPrimitive(fullTypeName)) { - ApiParam param = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName) - .setType(JavaClassUtil.getClassSimpleName(typeName)) - .setDesc(comment.toString()) - .setRequired(required) - .setMaxLength(JavaFieldUtil.getParamMaxLength(parameter.getAnnotations())) - .setValue(mockValue) - .setVersion(DocGlobalConstants.DEFAULT_VERSION); - paramList.add(param); - } else if (JavaClassValidateUtil.isMap(fullTypeName)) { - if (JavaClassValidateUtil.isMap(typeName)) { - ApiParam apiParam = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName).setType(typeName) - .setDesc(comment.toString()).setRequired(required).setVersion(DocGlobalConstants.DEFAULT_VERSION); - paramList.add(apiParam); - continue; - } - String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); - paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], paramPre, 0, "true", - Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); - } else if (javaClass.isEnum()) { - ApiParam param = ApiParam.of() - .setId(atomicInteger.incrementAndGet()) - .setField(paramName) - .setType(DocGlobalConstants.PARAM_TYPE_ENUM) - .setRequired(required) - .setDesc(comment.toString()) - .setVersion(DocGlobalConstants.DEFAULT_VERSION); - paramList.add(param); - } else { - paramList.addAll(ParamsBuildHelper.buildParams(typeName, paramPre, 0, "true", - Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); - } - } - return paramList; - } @Override public boolean isEntryPoint(JavaClass cls, FrameworkAnnotations frameworkAnnotations) { @@ -263,8 +112,8 @@ public FrameworkAnnotations registeredAnnotations() { private void handleJavaApiDoc(JavaClass cls, List apiDocList, List apiMethodDocs, int order, ProjectDocConfigBuilder builder) { String className = cls.getCanonicalName(); - String shortName = cls.getName(); String comment = cls.getComment(); + String shortName = cls.getName(); List javaTypes = cls.getImplements(); if (!javaTypes.isEmpty() && !cls.isInterface()) { JavaType javaType = javaTypes.get(0); diff --git a/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java b/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java index 391a8dea..2394ac89 100644 --- a/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java @@ -21,10 +21,8 @@ package com.ly.doc.template; import com.ly.doc.builder.ProjectDocConfigBuilder; -import com.ly.doc.constants.DocGlobalConstants; import com.ly.doc.constants.DocTags; import com.ly.doc.constants.DubboAnnotationConstants; -import com.ly.doc.helper.ParamsBuildHelper; import com.ly.doc.model.*; import com.ly.doc.model.annotation.FrameworkAnnotations; import com.ly.doc.model.rpc.RpcApiDoc; @@ -38,13 +36,18 @@ import java.util.concurrent.atomic.AtomicInteger; import java.util.stream.Collectors; -import static com.ly.doc.constants.DocTags.IGNORE; /** * @author yu 2020/1/29. */ public class RpcDocBuildTemplate implements IDocBuildTemplate, IWebSocketDocBuildTemplate, IRpcDocTemplate { + + @Override + public boolean addMethodModifiers() { + return false; + } + /** * api index */ @@ -57,14 +60,7 @@ public List renderApi(ProjectDocConfigBuilder projectBuilder, Collect int order = 0; boolean setCustomOrder = false; for (JavaClass cls : candidateClasses) { - if (StringUtil.isNotEmpty(apiConfig.getPackageFilters())) { - // check package - if (!DocUtil.isMatch(apiConfig.getPackageFilters(), cls)) { - continue; - } - } - DocletTag ignoreTag = cls.getTagByName(DocTags.IGNORE); - if (!isEntryPoint(cls, null) || Objects.nonNull(ignoreTag)) { + if (skipClass(apiConfig, cls, null)) { continue; } String strOrder = JavaClassUtil.getClassTagsValue(cls, DocTags.ORDER, Boolean.TRUE); @@ -73,7 +69,7 @@ public List renderApi(ProjectDocConfigBuilder projectBuilder, Collect order = Integer.parseInt(strOrder); setCustomOrder = true; } - List apiMethodDocs = buildServiceMethod(cls, apiConfig, projectBuilder); + List apiMethodDocs = (List) buildServiceMethod(cls, apiConfig, projectBuilder); this.handleJavaApiDoc(cls, apiDocList, apiMethodDocs, order, projectBuilder); } // sort @@ -98,155 +94,6 @@ public boolean ignoreReturnObject(String typeName, List ignoreParams) { return false; } - private List buildServiceMethod(final JavaClass cls, ApiConfig apiConfig, ProjectDocConfigBuilder projectBuilder) { - String clazName = cls.getCanonicalName(); - List methods = cls.getMethods(); - List methodDocList = new ArrayList<>(methods.size()); - - Set filterMethods = DocUtil.findFilterMethods(clazName); - boolean needAllMethods = filterMethods.contains(DocGlobalConstants.DEFAULT_FILTER_METHOD); - - for (JavaMethod method : methods) { - if (method.isPrivate()) { - continue; - } - if (Objects.nonNull(method.getTagByName(IGNORE))) { - continue; - } - if (StringUtil.isEmpty(method.getComment()) && apiConfig.isStrict()) { - throw new RuntimeException("Unable to find comment for method " + method.getName() + " in " + cls.getCanonicalName()); - } - if (needAllMethods || filterMethods.contains(method.getName())) { - RpcJavaMethod apiMethodDoc = convertToRpcJavaMethod(apiConfig, method, null); - methodDocList.add(apiMethodDoc); - } - - - } - // add parent class methods - methodDocList.addAll(getParentsClassMethods(apiConfig, cls)); - if (cls.isInterface() || cls.isAbstract()) { - methodDocList.addAll(getInterfaceMethods(apiConfig,cls)); - } - - int methodOrder = 0; - List rpcJavaMethods = new ArrayList<>(methodDocList.size()); - for (RpcJavaMethod method : methodDocList) { - methodOrder++; - method.setOrder(methodOrder); - String methodUid = DocUtil.generateId(clazName + method.getName() + methodOrder); - method.setMethodId(methodUid); - // build request params - List requestParams = requestParams(method.getJavaMethod(), projectBuilder, - new AtomicInteger(0), method.getActualTypesMap()); - // build response params - List responseParams = buildReturnApiParams(DocJavaMethod.builder().setJavaMethod(method.getJavaMethod()) - .setActualTypesMap(method.getActualTypesMap()), projectBuilder); - if (apiConfig.isParamsDataToTree()) { - method.setRequestParams(ApiParamTreeUtil.apiParamToTree(requestParams)); - method.setResponseParams(ApiParamTreeUtil.apiParamToTree(responseParams)); - } else { - method.setRequestParams(requestParams); - method.setResponseParams(responseParams); - } - rpcJavaMethods.add(method); - } - return rpcJavaMethods; - } - - private List requestParams(final JavaMethod javaMethod, - ProjectDocConfigBuilder builder, - AtomicInteger atomicInteger, - Map actualTypesMap) { - boolean isStrict = builder.getApiConfig().isStrict(); - boolean isShowJavaType = builder.getApiConfig().getShowJavaType(); - boolean isShowValidation = builder.getApiConfig().isShowValidation(); - String className = javaMethod.getDeclaringClass().getCanonicalName(); - Map paramTagMap = DocUtil.getCommentsByTag(javaMethod, DocTags.PARAM, className); - List parameterList = javaMethod.getParameters(); - if (parameterList.isEmpty()) { - return null; - } - ClassLoader classLoader = builder.getApiConfig().getClassLoader(); - List paramList = new ArrayList<>(); - for (JavaParameter parameter : parameterList) { - boolean required = false; - String paramName = parameter.getName(); - String typeName = replaceTypeName(parameter.getType().getGenericCanonicalName(), actualTypesMap, Boolean.FALSE); - String simpleName = replaceTypeName(parameter.getType().getValue(), actualTypesMap, Boolean.FALSE).toLowerCase(); - String fullTypeName = replaceTypeName(parameter.getType().getFullyQualifiedName(), actualTypesMap, Boolean.FALSE); - String paramPre = paramName + "."; - if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(fullTypeName) && 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))); - String mockValue = JavaFieldUtil.createMockValue(paramTagMap, paramName, typeName, typeName); - JavaClass javaClass = builder.getJavaProjectBuilder().getClassByName(fullTypeName); - List annotations = parameter.getAnnotations(); - for (JavaAnnotation a : annotations) { - if (JavaClassValidateUtil.isJSR303Required(a.getType().getValue())) { - required = true; - } - } - comment.append(JavaFieldUtil.getJsrComment(isShowValidation, classLoader, annotations)); - Set groupClasses = JavaClassUtil.getParamGroupJavaClass(annotations, builder.getJavaProjectBuilder()); - if (JavaClassValidateUtil.isCollection(fullTypeName) || JavaClassValidateUtil.isArray(fullTypeName)) { - if (JavaClassValidateUtil.isCollection(typeName)) { - typeName = typeName + ""; - } - String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); - String gicName = gicNameArr[0]; - if (JavaClassValidateUtil.isArray(gicName)) { - gicName = gicName.substring(0, gicName.indexOf("[")); - } - if (JavaClassValidateUtil.isPrimitive(gicName)) { - String processedType = isShowJavaType ? - JavaClassUtil.getClassSimpleName(typeName) : DocClassUtil.processTypeNameForParams(simpleName); - ApiParam param = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName) - .setDesc(comment + " (children type : " + gicName + ")") - .setRequired(required) - .setType(processedType); - paramList.add(param); - } else { - paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], paramPre, 0, "true", - Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); - } - } else if (JavaClassValidateUtil.isPrimitive(fullTypeName)) { - ApiParam param = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName) - .setType(JavaClassUtil.getClassSimpleName(typeName)) - .setDesc(comment.toString()) - .setRequired(required) - .setMaxLength(JavaFieldUtil.getParamMaxLength(parameter.getAnnotations())) - .setValue(mockValue) - .setVersion(DocGlobalConstants.DEFAULT_VERSION); - paramList.add(param); - } else if (JavaClassValidateUtil.isMap(fullTypeName)) { - if (JavaClassValidateUtil.isMap(typeName)) { - ApiParam apiParam = ApiParam.of().setId(atomicInteger.incrementAndGet()).setField(paramName).setType(typeName) - .setDesc(comment.toString()).setRequired(required).setVersion(DocGlobalConstants.DEFAULT_VERSION); - paramList.add(apiParam); - continue; - } - String[] gicNameArr = DocClassUtil.getSimpleGicName(typeName); - paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[1], paramPre, 0, "true", - Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); - } else if (javaClass.isEnum()) { - ApiParam param = ApiParam.of() - .setId(atomicInteger.incrementAndGet()) - .setField(paramName) - .setType(DocGlobalConstants.PARAM_TYPE_ENUM) - .setRequired(required) - .setDesc(comment.toString()) - .setVersion(DocGlobalConstants.DEFAULT_VERSION); - paramList.add(param); - } else { - paramList.addAll(ParamsBuildHelper.buildParams(typeName, paramPre, 0, "true", - Boolean.FALSE, new HashMap<>(16), builder, groupClasses, 0, Boolean.FALSE, atomicInteger)); - } - } - return paramList; - } @Override public boolean isEntryPoint(JavaClass cls, FrameworkAnnotations frameworkAnnotations) {