From 439fda087de435e53a9b48d3753069c5562935d2 Mon Sep 17 00:00:00 2001 From: linwumingshi Date: Sun, 15 Sep 2024 11:20:04 +0800 Subject: [PATCH] refactor: update java doc And error log --- .../com/ly/doc/builder/AdocDocBuilder.java | 6 + .../com/ly/doc/builder/ApiDataBuilder.java | 10 ++ .../com/ly/doc/builder/HtmlApiDocBuilder.java | 11 ++ .../com/ly/doc/builder/JMeterBuilder.java | 3 + .../ly/doc/builder/PostmanJsonBuilder.java | 6 + .../doc/builder/ProjectDocConfigBuilder.java | 100 ++++++++++++- .../com/ly/doc/builder/WordDocBuilder.java | 16 ++- .../builder/javadoc/JavadocAdocBuilder.java | 12 ++ .../javadoc/JavadocApiDataBuilder.java | 6 + .../javadoc/JavadocDocBuilderTemplate.java | 3 + .../builder/javadoc/JavadocHtmlBuilder.java | 6 + .../javadoc/JavadocMarkdownBuilder.java | 6 + .../openapi/AbstractOpenApiBuilder.java | 132 +++++++++++------- .../doc/builder/openapi/OpenApiBuilder.java | 35 +++-- .../doc/builder/openapi/SwaggerBuilder.java | 43 +++--- .../ly/doc/builder/rpc/RpcAdocBuilder.java | 9 ++ .../ly/doc/builder/rpc/RpcHtmlBuilder.java | 3 + .../doc/constants/ApiReqParamInTypeEnum.java | 13 ++ .../ly/doc/constants/ComponentTypeEnum.java | 12 ++ .../com/ly/doc/constants/DocLanguage.java | 8 ++ .../java/com/ly/doc/constants/DocTags.java | 5 + .../constants/DubboAnnotationConstants.java | 10 +- .../com/ly/doc/constants/FrameworkEnum.java | 18 +++ .../ly/doc/constants/GrpcMethodTypeEnum.java | 8 ++ .../doc/constants/HighLightJsConstants.java | 15 ++ .../com/ly/doc/constants/HighlightStyle.java | 63 ++++++--- .../ly/doc/constants/JAXRSAnnotations.java | 3 + .../doc/constants/JSRAnnotationConstants.java | 2 + .../constants/JSRAnnotationPropConstants.java | 11 ++ .../constants/JakartaJaxrsAnnotations.java | 33 ++++- ...JsonPropertyAnnotationAccessConstants.java | 11 ++ .../ly/doc/constants/SolonAnnotations.java | 2 + .../SolonRequestAnnotationsEnum.java | 2 + .../doc/constants/SpringMvcAnnotations.java | 3 + .../SpringMvcRequestAnnotationsEnum.java | 8 ++ .../ly/doc/constants/TemplateVariable.java | 10 ++ .../com/ly/doc/constants/TornaConstants.java | 67 +++++++-- .../doc/constants/ValidatorAnnotations.java | 2 + .../dict/DictionaryValuesResolver.java | 2 + .../extension/json/PropertyNameHelper.java | 66 ++++++++- .../json/PropertyNamingStrategies.java | 26 +++- .../com/ly/doc/filter/BoxReturnFilter.java | 12 +- .../ly/doc/filter/ReturnTypeProcessor.java | 18 ++- .../ly/doc/filter/WebFluxReturnFilter.java | 6 +- .../doc/handler/ICustomJavaMethodHandler.java | 6 + .../com/ly/doc/handler/IHeaderHandler.java | 35 +++-- .../doc/handler/IRequestMappingHandler.java | 30 +++- .../ly/doc/handler/JaxrsHeaderHandler.java | 38 +++-- .../com/ly/doc/handler/JaxrsPathHandler.java | 51 +++++-- .../handler/SolonRequestHeaderHandler.java | 2 + .../handler/SolonRequestMappingHandler.java | 2 + .../SpringMVCRequestHeaderHandler.java | 2 + .../SpringMVCRequestMappingHandler.java | 9 +- .../java/com/ly/doc/helper/BaseHelper.java | 18 ++- .../com/ly/doc/helper/DocBuildHelper.java | 73 +++++++++- .../ly/doc/helper/FormDataBuildHelper.java | 2 + .../java/com/ly/doc/helper/GitHelper.java | 40 ++++++ .../doc/helper/JavaProjectBuilderHelper.java | 16 +++ .../com/ly/doc/helper/JsonBuildHelper.java | 2 + .../com/ly/doc/helper/ParamsBuildHelper.java | 2 + .../java/com/ly/doc/model/ApiConstant.java | 14 +- src/main/java/com/ly/doc/model/ApiSchema.java | 7 +- .../java/com/ly/doc/model/BodyAdvice.java | 12 +- src/main/java/com/ly/doc/model/FormData.java | 3 +- .../ly/doc/template/GRpcDocBuildTemplate.java | 4 +- .../doc/template/IBaseDocBuildTemplate.java | 56 +++++++- .../doc/template/IDocBuildBaseTemplate.java | 4 +- .../ly/doc/template/IDocBuildTemplate.java | 3 + .../ly/doc/template/IJavadocDocTemplate.java | 8 +- .../com/ly/doc/template/IRestDocTemplate.java | 2 +- .../doc/template/JAXRSDocBuildTemplate.java | 11 +- .../doc/template/JavadocDocBuildTemplate.java | 11 ++ .../ly/doc/template/RpcDocBuildTemplate.java | 12 ++ .../doc/template/SolonDocBuildTemplate.java | 2 +- .../template/SpringBootDocBuildTemplate.java | 4 +- .../com/ly/doc/utils/ApiParamTreeUtil.java | 14 ++ .../com/ly/doc/utils/BeetlTemplateUtil.java | 20 ++- src/main/java/com/ly/doc/utils/CurlUtil.java | 12 ++ .../java/com/ly/doc/utils/DocClassUtil.java | 26 +++- .../java/com/ly/doc/utils/DocPathUtil.java | 7 + .../java/com/ly/doc/utils/DocUrlUtil.java | 45 +++++- src/main/java/com/ly/doc/utils/DocUtil.java | 37 +++-- .../java/com/ly/doc/utils/HttpStatusUtil.java | 9 ++ src/main/java/com/ly/doc/utils/Iterables.java | 21 ++- .../java/com/ly/doc/utils/JavaClassUtil.java | 58 +++++++- .../ly/doc/utils/JavaClassValidateUtil.java | 40 ++++-- .../java/com/ly/doc/utils/JavaFieldUtil.java | 23 ++- src/main/java/com/ly/doc/utils/JsonUtil.java | 16 +++ .../com/ly/doc/utils/OpenApiSchemaUtil.java | 78 ++++++++--- src/main/java/com/ly/doc/utils/ParamUtil.java | 19 +++ .../com/ly/doc/utils/RequestExampleUtil.java | 9 +- src/main/java/com/ly/doc/utils/TornaUtil.java | 7 + 92 files changed, 1478 insertions(+), 287 deletions(-) diff --git a/src/main/java/com/ly/doc/builder/AdocDocBuilder.java b/src/main/java/com/ly/doc/builder/AdocDocBuilder.java index bebe7009..1c72670e 100644 --- a/src/main/java/com/ly/doc/builder/AdocDocBuilder.java +++ b/src/main/java/com/ly/doc/builder/AdocDocBuilder.java @@ -38,8 +38,14 @@ */ public class AdocDocBuilder { + /** + * api doc file name + */ private static final String API_EXTENSION = "Api.adoc"; + /** + * index.adoc + */ private static final String INDEX_DOC = "index.adoc"; /** diff --git a/src/main/java/com/ly/doc/builder/ApiDataBuilder.java b/src/main/java/com/ly/doc/builder/ApiDataBuilder.java index dbb4bbab..73f57526 100644 --- a/src/main/java/com/ly/doc/builder/ApiDataBuilder.java +++ b/src/main/java/com/ly/doc/builder/ApiDataBuilder.java @@ -26,6 +26,8 @@ import com.thoughtworks.qdox.JavaProjectBuilder; /** + * Build Api Data + * * @author yu 2019/12/7. * @since 1.7.9 */ @@ -56,6 +58,14 @@ public static ApiAllData getApiDataTree(ApiConfig config) { return getApiData(config, Boolean.TRUE); } + /** + * Retrieves API data based on the given configuration. + * @param config The API configuration object containing request parameters and data + * source information. + * @param toTree A flag indicating whether to convert the parameter data into a tree + * structure. + * @return An ApiAllData object containing all the API data information. + */ private static ApiAllData getApiData(ApiConfig config, boolean toTree) { config.setParamsDataToTree(toTree); DocBuilderTemplate builderTemplate = new DocBuilderTemplate(); diff --git a/src/main/java/com/ly/doc/builder/HtmlApiDocBuilder.java b/src/main/java/com/ly/doc/builder/HtmlApiDocBuilder.java index 79ae4215..94e45192 100644 --- a/src/main/java/com/ly/doc/builder/HtmlApiDocBuilder.java +++ b/src/main/java/com/ly/doc/builder/HtmlApiDocBuilder.java @@ -36,15 +36,26 @@ import java.util.Objects; /** + * HTML API Doc Builder + * * @author yu 2019/9/20. * @since 1.7+ */ public class HtmlApiDocBuilder { + /** + * error code html + */ private static final String ERROR_CODE_HTML = "error.html"; + /** + * dict html + */ private static final String DICT_HTML = "dict.html"; + /** + * index html + */ private static String INDEX_HTML = "index.html"; /** diff --git a/src/main/java/com/ly/doc/builder/JMeterBuilder.java b/src/main/java/com/ly/doc/builder/JMeterBuilder.java index e96fec04..23a89430 100644 --- a/src/main/java/com/ly/doc/builder/JMeterBuilder.java +++ b/src/main/java/com/ly/doc/builder/JMeterBuilder.java @@ -41,6 +41,9 @@ */ public class JMeterBuilder { + /** + * Jmeter script extension + */ private static final String JMETER_SCRIPT_EXTENSION = ".jmx"; /** diff --git a/src/main/java/com/ly/doc/builder/PostmanJsonBuilder.java b/src/main/java/com/ly/doc/builder/PostmanJsonBuilder.java index c326c3dd..92bd74d1 100644 --- a/src/main/java/com/ly/doc/builder/PostmanJsonBuilder.java +++ b/src/main/java/com/ly/doc/builder/PostmanJsonBuilder.java @@ -45,10 +45,16 @@ import java.util.*; /** + * Postman Json Builder + * * @author yu 2019/11/21. + * @since 1.7.8 */ public class PostmanJsonBuilder { + /** + * Message + */ private static final String MSG = "Interface name is not set."; /** diff --git a/src/main/java/com/ly/doc/builder/ProjectDocConfigBuilder.java b/src/main/java/com/ly/doc/builder/ProjectDocConfigBuilder.java index d38ac45b..ac518d53 100644 --- a/src/main/java/com/ly/doc/builder/ProjectDocConfigBuilder.java +++ b/src/main/java/com/ly/doc/builder/ProjectDocConfigBuilder.java @@ -47,30 +47,68 @@ import java.util.logging.Logger; /** + * ProjectDocConfigBuilder + * * @author yu 2019/12/21. + * @since 1.8.0 */ public class ProjectDocConfigBuilder { + /** + * Logger + */ private static final Logger log = Logger.getLogger(ProjectDocConfigBuilder.class.getName()); + /** + * JavaProjectBuilder + */ private final JavaProjectBuilder javaProjectBuilder; + /** + * classFilesMap + */ private final Map classFilesMap = new ConcurrentHashMap<>(); + /** + * enumClassMap + */ private final Map>> enumClassMap = new ConcurrentHashMap<>(); + /** + * customRespFieldMap + */ private final Map customRespFieldMap = new ConcurrentHashMap<>(); + /** + * customReqFieldMap + */ private final Map customReqFieldMap = new ConcurrentHashMap<>(); + /** + * replaceClassMap + */ private final Map replaceClassMap = new ConcurrentHashMap<>(); + /** + * constantsMap + */ private final Map constantsMap = new ConcurrentHashMap<>(); + /** + * serverUrl + */ private final String serverUrl; + /** + * ApiConfig + */ private final ApiConfig apiConfig; + /** + * Constructor + * @param apiConfig ApiConfig + * @param javaProjectBuilder JavaProjectBuilder + */ public ProjectDocConfigBuilder(ApiConfig apiConfig, JavaProjectBuilder javaProjectBuilder) { if (null == apiConfig) { throw new NullPointerException("ApiConfig can't be null."); @@ -105,6 +143,10 @@ public ProjectDocConfigBuilder(ApiConfig apiConfig, JavaProjectBuilder javaProje this.checkBodyAdvice(apiConfig.getResponseBodyAdvice()); } + /** + * Init data dictionary. + * @param apiConfig apiConfig + */ private void initDict(ApiConfig apiConfig) { if (enumClassMap.isEmpty()) { return; @@ -129,6 +171,11 @@ private void initDict(ApiConfig apiConfig) { } } + /** + * Get enum implements by interface. + * @param enumClass enumClass + * @return enum implements + */ private Set>> getEnumImplementsByInterface(Class enumClass) { if (!enumClass.isInterface()) { return Collections.emptySet(); @@ -142,6 +189,11 @@ private Set>> getEnumImplementsByInterface(Class enum return set; } + /** + * Get class by name. + * @param simpleName simpleName + * @return JavaClass + */ public JavaClass getClassByName(String simpleName) { JavaClass cls = javaProjectBuilder.getClassByName(simpleName); List fieldList = JavaClassUtil.getFields(cls, 0, new LinkedHashMap<>(), null); @@ -158,6 +210,11 @@ public JavaClass getClassByName(String simpleName) { return cls; } + /** + * Load java source. + * @param config ApiConfig + * @param builder JavaProjectBuilder + */ private void loadJavaSource(ApiConfig config, JavaProjectBuilder builder) { if (CollectionUtil.isNotEmpty(config.getJarSourcePaths())) { for (SourceCodePath path : config.getJarSourcePaths()) { @@ -181,6 +238,11 @@ private void loadJavaSource(ApiConfig config, JavaProjectBuilder builder) { } } + /** + * Load jar java source. + * @param strPath path + * @param builder builder + */ private void loadJavaSource(String strPath, JavaProjectBuilder builder) { DirectoryScanner scanner = new DirectoryScanner(new File(strPath)); scanner.addFilter(new SuffixFilter(".java")); @@ -194,6 +256,11 @@ private void loadJavaSource(String strPath, JavaProjectBuilder builder) { }); } + /** + * Load jar java source. + * @param path path + * @param builder builder + */ public void loadJarJavaSource(String path, JavaProjectBuilder builder) { OutputStream out; if (!path.endsWith(".jar")) { @@ -228,6 +295,10 @@ public void loadJarJavaSource(String path, JavaProjectBuilder builder) { } } + /** + * Delete dir. + * @param file file + */ public static void deleteDir(File file) { File[] files = file.listFiles(); if (file.isFile() || Objects.isNull(files) || files.length == 0) { @@ -241,6 +312,10 @@ public static void deleteDir(File file) { file.delete(); } + /** + * Init class files map. + */ + @SuppressWarnings({ "rawtypes", "unchecked" }) private void initClassFilesMap() { Collection javaClasses = javaProjectBuilder.getClasses(); for (JavaClass cls : javaClasses) { @@ -264,6 +339,10 @@ private void initClassFilesMap() { } } + /** + * Init custom response fields map. + * @param config config + */ private void initCustomResponseFieldsMap(ApiConfig config) { if (CollectionUtil.isNotEmpty(config.getCustomResponseFields())) { for (CustomField field : config.getCustomResponseFields()) { @@ -273,6 +352,10 @@ private void initCustomResponseFieldsMap(ApiConfig config) { } } + /** + * Init custom request fields map. + * @param config config + */ private void initCustomRequestFieldsMap(ApiConfig config) { if (CollectionUtil.isNotEmpty(config.getCustomRequestFields())) { for (CustomField field : config.getCustomRequestFields()) { @@ -282,6 +365,10 @@ private void initCustomRequestFieldsMap(ApiConfig config) { } } + /** + * Init replace class map. + * @param config config + */ private void initReplaceClassMap(ApiConfig config) { if (CollectionUtil.isNotEmpty(config.getApiObjectReplacements())) { for (ApiObjectReplacement replace : config.getApiObjectReplacements()) { @@ -290,6 +377,10 @@ private void initReplaceClassMap(ApiConfig config) { } } + /** + * Init constants. + * @param config config + */ private void initConstants(ApiConfig config) { List apiConstants; if (CollectionUtil.isEmpty(config.getApiConstants())) { @@ -311,10 +402,14 @@ private void initConstants(ApiConfig config) { } } catch (ClassNotFoundException | IllegalAccessException e) { - e.printStackTrace(); + log.warning(e.getMessage()); } } + /** + * Check body advice. + * @param bodyAdvice body advice + */ private void checkBodyAdvice(BodyAdvice bodyAdvice) { if (Objects.nonNull(bodyAdvice) && StringUtil.isNotEmpty(bodyAdvice.getClassName())) { if (Objects.nonNull(bodyAdvice.getWrapperClass())) { @@ -330,6 +425,9 @@ private void checkBodyAdvice(BodyAdvice bodyAdvice) { } } + /** + * Set highlight style. + */ private void setHighlightStyle() { String style = apiConfig.getStyle(); if (HighLightJsConstants.HIGH_LIGHT_DEFAULT_STYLE.equals(style)) { diff --git a/src/main/java/com/ly/doc/builder/WordDocBuilder.java b/src/main/java/com/ly/doc/builder/WordDocBuilder.java index 0a06909a..9da6e061 100644 --- a/src/main/java/com/ly/doc/builder/WordDocBuilder.java +++ b/src/main/java/com/ly/doc/builder/WordDocBuilder.java @@ -43,17 +43,31 @@ import java.util.zip.ZipOutputStream; /** + * Word doc builder + * * @author chenqi - * @version 1.0 + * @since 3.0.1 */ public class WordDocBuilder { + /** + * template docx + */ private static final String TEMPLATE_DOCX = "template/word/template.docx"; + /** + * build docx file name + */ private static final String BUILD_DOCX = "index.docx"; + /** + * build error code docx file name + */ private static final String BUILD_ERROR_DOCX = "error.docx"; + /** + * build directory data docx file name + */ private static final String BUILD_DICT_DOCX = "dict.docx"; /** diff --git a/src/main/java/com/ly/doc/builder/javadoc/JavadocAdocBuilder.java b/src/main/java/com/ly/doc/builder/javadoc/JavadocAdocBuilder.java index 69689d07..8da56797 100644 --- a/src/main/java/com/ly/doc/builder/javadoc/JavadocAdocBuilder.java +++ b/src/main/java/com/ly/doc/builder/javadoc/JavadocAdocBuilder.java @@ -28,10 +28,22 @@ import java.util.List; +/** + * Javadoc Asciidoc Builder + * + * @author chenchuxin + * @since 3.0.5 + */ public class JavadocAdocBuilder { + /** + * api extension + */ private static final String API_EXTENSION = "JavadocApi.adoc"; + /** + * index extension + */ private static final String INDEX_DOC = "javadoc-index.adoc"; /** diff --git a/src/main/java/com/ly/doc/builder/javadoc/JavadocApiDataBuilder.java b/src/main/java/com/ly/doc/builder/javadoc/JavadocApiDataBuilder.java index 619fd72d..ee409b7e 100644 --- a/src/main/java/com/ly/doc/builder/javadoc/JavadocApiDataBuilder.java +++ b/src/main/java/com/ly/doc/builder/javadoc/JavadocApiDataBuilder.java @@ -26,6 +26,12 @@ import com.ly.doc.model.javadoc.JavadocApiAllData; import com.thoughtworks.qdox.JavaProjectBuilder; +/** + * Javadoc Api Data Builder + * + * @author chenchuxin + * @since 3.0.5 + */ public class JavadocApiDataBuilder { /** diff --git a/src/main/java/com/ly/doc/builder/javadoc/JavadocDocBuilderTemplate.java b/src/main/java/com/ly/doc/builder/javadoc/JavadocDocBuilderTemplate.java index f3e5479a..ee6a4413 100644 --- a/src/main/java/com/ly/doc/builder/javadoc/JavadocDocBuilderTemplate.java +++ b/src/main/java/com/ly/doc/builder/javadoc/JavadocDocBuilderTemplate.java @@ -53,6 +53,9 @@ */ public class JavadocDocBuilderTemplate implements IBaseDocBuilderTemplate { + /** + * dependency title + */ private static final String DEPENDENCY_TITLE = "Add dependency"; @Override diff --git a/src/main/java/com/ly/doc/builder/javadoc/JavadocHtmlBuilder.java b/src/main/java/com/ly/doc/builder/javadoc/JavadocHtmlBuilder.java index 89c1be6e..60eefed3 100644 --- a/src/main/java/com/ly/doc/builder/javadoc/JavadocHtmlBuilder.java +++ b/src/main/java/com/ly/doc/builder/javadoc/JavadocHtmlBuilder.java @@ -28,6 +28,12 @@ import java.util.List; +/** + * Javadoc Html Builder + * + * @author chenchuxin + * @since 3.0.5 + */ public class JavadocHtmlBuilder { /** diff --git a/src/main/java/com/ly/doc/builder/javadoc/JavadocMarkdownBuilder.java b/src/main/java/com/ly/doc/builder/javadoc/JavadocMarkdownBuilder.java index 0922e7ed..cef2c92c 100644 --- a/src/main/java/com/ly/doc/builder/javadoc/JavadocMarkdownBuilder.java +++ b/src/main/java/com/ly/doc/builder/javadoc/JavadocMarkdownBuilder.java @@ -29,6 +29,12 @@ import java.util.List; +/** + * Javadoc Markdown Builder + * + * @author chenchuxin + * @since 3.0.5 + */ public class JavadocMarkdownBuilder { /** diff --git a/src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java b/src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java index 041a9f16..54c7ca87 100644 --- a/src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java +++ b/src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java @@ -43,21 +43,38 @@ import static com.ly.doc.constants.DocGlobalConstants.OPENAPI_3_COMPONENT_KRY; /** + * abstract openapi builder + * * @author xingzi Date 2022/10/12 18:49 + * @since 2.6.2 */ -@SuppressWarnings("all") public abstract class AbstractOpenApiBuilder { + /** + * Component key + */ private String componentKey; + /** + * Get component key + * @return component key + */ public String getComponentKey() { return componentKey; } + /** + * Set component key + * @param componentKey component key + */ public void setComponentKey(String componentKey) { this.componentKey = componentKey; } + /** + * Get module name + * @return module name + */ abstract String getModuleName(); /** @@ -89,9 +106,16 @@ abstract Map buildPathUrlsRequest(ApiConfig apiConfig, ApiMethod /** * Build request parameters * @param apiMethodDoc API data for the method + * @return List of parameters */ abstract List> buildParameters(ApiMethodDoc apiMethodDoc); + /** + * Build request parameters + * @param apiParam ApiParam + * @param hasItems has items + * @return Map of request parameters + */ abstract Map getStringParams(ApiParam apiParam, boolean hasItems); /** @@ -101,6 +125,9 @@ abstract Map buildPathUrlsRequest(ApiConfig apiConfig, ApiMethod */ abstract public Map buildComponentsSchema(ApiSchema apiSchema); + /** + * String component + */ protected static final Map STRING_COMPONENT = new HashMap<>(); static { @@ -115,6 +142,7 @@ abstract Map buildPathUrlsRequest(ApiConfig apiConfig, ApiMethod * @param tags tags * @return Map of paths */ + @SuppressWarnings("unchecked") public Map buildPaths(ApiConfig apiConfig, ApiSchema apiSchema, Set tags) { Map pathMap = new LinkedHashMap<>(500); @@ -161,9 +189,9 @@ public Map buildPaths(ApiConfig apiConfig, ApiSchema api */ public Map buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc, List apiExceptionStatuses) { - Map request = new HashMap<>(4); + Map request = new HashMap<>(16); request.put(apiMethodDoc.getType().toLowerCase(), - buildPathUrlsRequest(apiConfig, apiMethodDoc, apiDoc, apiExceptionStatuses)); + this.buildPathUrlsRequest(apiConfig, apiMethodDoc, apiDoc, apiExceptionStatuses)); return request; } @@ -175,12 +203,12 @@ public Map buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMe * @return Map of content */ public Map buildContent(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, boolean isRep) { - Map content = new HashMap<>(8); + Map content = new HashMap<>(16); String contentType = apiMethodDoc.getContentType(); if (isRep) { contentType = "*/*"; } - content.put(contentType, buildContentBody(apiConfig, apiMethodDoc, isRep)); + content.put(contentType, this.buildContentBody(apiConfig, apiMethodDoc, isRep)); return content; } @@ -193,7 +221,7 @@ public Map buildContent(ApiConfig apiConfig, ApiMethodDoc apiMet * @return Map of content */ public Map buildContentBody(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, boolean isRep) { - Map content = new HashMap<>(8); + Map content = new HashMap<>(16); if (Objects.nonNull(apiMethodDoc.getReturnSchema()) && isRep) { content.put("schema", apiMethodDoc.getReturnSchema()); } @@ -201,7 +229,7 @@ else if (!isRep && Objects.nonNull(apiMethodDoc.getRequestSchema())) { content.put("schema", apiMethodDoc.getRequestSchema()); } else { - content.put("schema", buildBodySchema(apiMethodDoc, isRep)); + content.put("schema", this.buildBodySchema(apiMethodDoc, isRep)); } if (OPENAPI_2_COMPONENT_KRY.equals(componentKey) && !isRep) { @@ -246,10 +274,10 @@ else if (CollectionUtil.isNotEmpty(apiMethodDoc.getResponseParams())) { && (apiMethodDoc.getContentType().equals(MediaType.APPLICATION_FORM_URLENCODED_VALUE) || apiMethodDoc.getContentType().equals(MediaType.MULTIPART_FORM_DATA_VALUE))) { schema.put("type", ParamTypeConstants.PARAM_TYPE_OBJECT); - Map propertiesAndRequirments = buildProperties(apiMethodDoc.getRequestParams(), + Map propertiesAndRequiredMap = this.buildProperties(apiMethodDoc.getRequestParams(), new HashMap<>(), Boolean.FALSE); - schema.put("properties", propertiesAndRequirments.get("properties")); - schema.put("required", propertiesAndRequirments.get("required")); + schema.put("properties", propertiesAndRequiredMap.get("properties")); + schema.put("required", propertiesAndRequiredMap.get("required")); return schema; } else if (apiMethodDoc.getContentType().equals(MediaType.APPLICATION_FORM_URLENCODED_VALUE)) { @@ -318,34 +346,36 @@ public Map buildParametersSchema(ApiParam apiParam) { // The values of openApiType are "file", "object", "array","string", // "integer","number" schema.put("type", openApiType); - if ("file".equals(openApiType)) { - schema.put("format", "binary"); - schema.put("type", "string"); - } - else if ("object".equals(openApiType)) { - if ("enum".equals(apiParam.getType())) { - schema.put("enum", apiParam.getEnumValues()); - } - } - else if (ParamTypeConstants.PARAM_TYPE_ARRAY.equals(openApiType)) { - if (CollectionUtil.isNotEmpty(apiParam.getEnumValues())) { + switch (openApiType) { + case ParamTypeConstants.PARAM_TYPE_FILE: + schema.put("format", "binary"); schema.put("type", "string"); - schema.put("items", apiParam.getEnumValues()); - } - else { - schema.put("type", ParamTypeConstants.PARAM_TYPE_ARRAY); - Map map = new HashMap<>(4); - map.put("type", "string"); - map.put("format", "string"); - schema.put("items", map); - } - } - else { - // "string", "integer", "number" - schema.put("format", apiParam.getType()); - if ("enum".equals(apiParam.getType())) { - schema.put("enum", apiParam.getEnumValues()); - } + break; + case ParamTypeConstants.PARAM_TYPE_OBJECT: + if ("enum".equals(apiParam.getType())) { + schema.put("enum", apiParam.getEnumValues()); + } + break; + case ParamTypeConstants.PARAM_TYPE_ARRAY: + if (CollectionUtil.isNotEmpty(apiParam.getEnumValues())) { + schema.put("type", "string"); + schema.put("items", apiParam.getEnumValues()); + } + else { + schema.put("type", ParamTypeConstants.PARAM_TYPE_ARRAY); + Map map = new HashMap<>(4); + map.put("type", "string"); + map.put("format", "string"); + schema.put("items", map); + } + break; + default: + // "string", "integer", "number" + schema.put("format", apiParam.getType()); + if ("enum".equals(apiParam.getType())) { + schema.put("enum", apiParam.getEnumValues()); + } + break; } return schema; } @@ -373,17 +403,23 @@ public static Map buildParametersSchema(ApiReqParam header) { public Map buildResponses(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, List apiExceptionStatuses) { Map response = new LinkedHashMap<>(8); - response.put("200", buildResponsesBody(apiConfig, apiMethodDoc)); + response.put("200", this.buildResponsesBody(apiConfig, apiMethodDoc)); if (CollectionUtil.isNotEmpty(apiExceptionStatuses)) { for (ApiExceptionStatus apiExceptionStatus : apiExceptionStatuses) { response.put(apiExceptionStatus.getStatus(), - buildEexcetionResponsesBody(apiConfig, apiExceptionStatus)); + this.buildExceptionResponsesBody(apiConfig, apiExceptionStatus)); } } return response; } - public Map buildEexcetionResponsesBody(ApiConfig apiConfig, ApiExceptionStatus apiExceptionStatus) { + /** + * Build exception response body + * @param apiConfig ApiConfig + * @param apiExceptionStatus ApiExceptionStatus + * @return Map of content + */ + public Map buildExceptionResponsesBody(ApiConfig apiConfig, ApiExceptionStatus apiExceptionStatus) { Map responseBody = new HashMap<>(8); responseBody.put("description", apiExceptionStatus.getDesc()); Map content = new HashMap<>(8); @@ -432,7 +468,7 @@ public Map buildProperties(List apiParam, Map buildProperties(List apiParam, Map buildPropertiesData(ApiParam apiParam, Map component, boolean isResp) { - Map propertiesData = new HashMap<>(); + Map propertiesData = new HashMap<>(16); String openApiType = DocUtil.javaTypeToOpenApiTypeConvert(apiParam.getType()); // array object file map propertiesData.put("description", apiParam.getDesc()); @@ -486,7 +522,7 @@ private Map buildPropertiesData(ApiParam apiParam, Map buildPropertiesData(ApiParam apiParam, Map buildPropertiesData(ApiParam apiParam, Map propertiesData.put("x-" + e.getKey(), e.getValue())); + apiParam.getExtensions().forEach((key, value) -> propertiesData.put("x-" + key, value)); } return propertiesData; @@ -551,12 +587,12 @@ public Map buildComponentData(ApiSchema apiSchema) { component.put(responseSchemaName, this.buildProperties(responseParams, component, true)); }); }); - // excption response components + // Exception response components if (Objects.nonNull(apiSchema.getApiExceptionStatuses())) { apiSchema.getApiExceptionStatuses().forEach(e -> { List responseParams = e.getExceptionResponseParams(); String responseSchemaName = OpenApiSchemaUtil.getClassNameFromParams(e.getExceptionResponseParams()); - component.put(responseSchemaName, buildProperties(responseParams, component, true)); + component.put(responseSchemaName, this.buildProperties(responseParams, component, true)); }); } component.remove(OpenApiSchemaUtil.NO_BODY_PARAM); @@ -575,7 +611,7 @@ public ApiSchema getOpenApiDocs(ApiConfig config, JavaProjectBuilder pro builderTemplate.checkAndInit(config, Boolean.TRUE); ProjectDocConfigBuilder configBuilder = new ProjectDocConfigBuilder(config, projectBuilder); config.setParamsDataToTree(true); - IDocBuildTemplate docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework(), + IDocBuildTemplate docBuildTemplate = BuildTemplateFactory.getDocBuildTemplate(config.getFramework(), config.getClassLoader()); Objects.requireNonNull(docBuildTemplate, "doc build template is null"); return docBuildTemplate.getApiData(configBuilder); diff --git a/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java b/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java index 3acd7525..8dcb28a3 100644 --- a/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java +++ b/src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java @@ -39,17 +39,25 @@ import java.util.stream.Collectors; /** + * + * OpenApi Builder + * * @author xingzi + * @since 2.6.2 */ public class OpenApiBuilder extends AbstractOpenApiBuilder { - @Override - public String getModuleName() { - return DocGlobalConstants.OPENAPI_3_COMPONENT_KRY; - } - + /** + * Instance + */ private static final OpenApiBuilder INSTANCE = new OpenApiBuilder(); + /** + * private constructor + */ + private OpenApiBuilder() { + } + /** * For unit testing * @param config Configuration of smart-doc @@ -69,6 +77,11 @@ public static void buildOpenApi(ApiConfig config, JavaProjectBuilder projectBuil INSTANCE.openApiCreate(config, apiSchema); } + @Override + public String getModuleName() { + return DocGlobalConstants.OPENAPI_3_COMPONENT_KRY; + } + @Override public void openApiCreate(ApiConfig config, ApiSchema apiSchema) { this.setComponentKey(getModuleName()); @@ -177,7 +190,7 @@ public List> buildParameters(ApiMethodDoc apiMethodDoc) { List> parametersList = new ArrayList<>(); // Handling path parameters for (ApiParam apiParam : apiMethodDoc.getPathParams()) { - parameters = getStringParams(apiParam, apiParam.isHasItems()); + parameters = this.getStringParams(apiParam, apiParam.isHasItems()); parameters.put("in", "path"); List children = apiParam.getChildren(); if (CollectionUtil.isEmpty(children)) { @@ -186,15 +199,15 @@ public List> buildParameters(ApiMethodDoc apiMethodDoc) { } for (ApiParam apiParam : apiMethodDoc.getQueryParams()) { if (apiParam.isHasItems()) { - parameters = getStringParams(apiParam, false); + parameters = this.getStringParams(apiParam, false); Map arrayMap = new HashMap<>(16); arrayMap.put("type", ParamTypeConstants.PARAM_TYPE_ARRAY); - arrayMap.put("items", getStringParams(apiParam, apiParam.isHasItems())); + arrayMap.put("items", this.getStringParams(apiParam, apiParam.isHasItems())); parameters.put("schema", arrayMap); parametersList.add(parameters); } else { - parameters = getStringParams(apiParam, false); + parameters = this.getStringParams(apiParam, false); List children = apiParam.getChildren(); if (CollectionUtil.isEmpty(children)) { parametersList.add(parameters); @@ -230,7 +243,7 @@ public Map getStringParams(ApiParam apiParam, boolean hasItems) parameters.put("description", apiParam.getDesc()); parameters.put("required", apiParam.isRequired()); parameters.put("in", "query"); - parameters.put("schema", buildParametersSchema(apiParam)); + parameters.put("schema", this.buildParametersSchema(apiParam)); } else { if (ParamTypeConstants.PARAM_TYPE_OBJECT.equals(apiParam.getType()) @@ -250,7 +263,7 @@ else if (desc.contains("string")) { parameters.put("type", "integer"); } } - parameters.putAll(buildParametersSchema(apiParam)); + parameters.putAll(this.buildParametersSchema(apiParam)); } if (apiParam.getExtensions() != null && !apiParam.getExtensions().isEmpty()) { apiParam.getExtensions().forEach((key, value) -> parameters.put("x-" + key, value)); diff --git a/src/main/java/com/ly/doc/builder/openapi/SwaggerBuilder.java b/src/main/java/com/ly/doc/builder/openapi/SwaggerBuilder.java index 03370e98..21c6c2c9 100644 --- a/src/main/java/com/ly/doc/builder/openapi/SwaggerBuilder.java +++ b/src/main/java/com/ly/doc/builder/openapi/SwaggerBuilder.java @@ -36,15 +36,27 @@ import org.apache.commons.lang3.StringUtils; import java.util.*; +import java.util.stream.Stream; /** + * Swagger Builder + * * @author xingzi Date 2022/9/17 15:16 + * @since 2.6.2 */ -@SuppressWarnings("all") public class SwaggerBuilder extends AbstractOpenApiBuilder { + /** + * Singleton + */ private static final SwaggerBuilder INSTANCE = new SwaggerBuilder(); + /** + * private constructor + */ + private SwaggerBuilder() { + } + /** * For unit testing * @param config Configuration of smart-doc @@ -133,25 +145,24 @@ public Map buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDo request.put("summary", apiMethodDoc.getDesc()); request.put("description", apiMethodDoc.getDetail()); request.put("tags", - Arrays.asList(apiDoc.getName(), apiDoc.getDesc(), apiMethodDoc.getGroup()) - .stream() + Stream.of(apiDoc.getName(), apiDoc.getDesc(), apiMethodDoc.getGroup()) .filter(StringUtil::isNotEmpty) - .toArray(n -> new String[n])); + .toArray(String[]::new)); List> parameters = this.buildParameters(apiMethodDoc); // requestBody if (CollectionUtil.isNotEmpty(apiMethodDoc.getRequestParams())) { - Map parameter = new HashMap<>(); + Map parameter = new HashMap<>(16); parameter.put("in", "body"); - parameter.putAll(buildContentBody(apiConfig, apiMethodDoc, false)); + parameter.putAll(this.buildContentBody(apiConfig, apiMethodDoc, false)); parameters.add(parameter); } - if (hasFile(parameters)) { + if (this.hasFile(parameters)) { List formData = new ArrayList<>(); formData.add(MediaType.MULTIPART_FORM_DATA); request.put("consumes", formData); } request.put("parameters", parameters); - request.put("responses", buildResponses(apiConfig, apiMethodDoc, apiExceptionStatuses)); + request.put("responses", this.buildResponses(apiConfig, apiMethodDoc, apiExceptionStatuses)); request.put("deprecated", apiMethodDoc.isDeprecated()); String operationId = apiMethodDoc.getUrl().replace(apiMethodDoc.getServerUrl(), ""); // make sure operationId is unique and can be used as a method name @@ -163,8 +174,8 @@ public Map buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDo /** * Check if the parameter contains a file - * @param parameters - * @return + * @param parameters list of parameters + * @return true if it contains a file */ private boolean hasFile(List> parameters) { for (Map param : parameters) { @@ -185,7 +196,7 @@ public Map buildResponsesBody(ApiConfig apiConfig, ApiMethodDoc responseBody.put("description", "OK"); if (CollectionUtil.isNotEmpty(apiMethodDoc.getResponseParams()) || Objects.nonNull(apiMethodDoc.getReturnSchema())) { - responseBody.putAll(buildContentBody(apiConfig, apiMethodDoc, true)); + responseBody.putAll(this.buildContentBody(apiConfig, apiMethodDoc, true)); } return responseBody; } @@ -197,20 +208,20 @@ public List> buildParameters(ApiMethodDoc apiMethodDoc) { List> parametersList = new ArrayList<>(); // Handling path parameters for (ApiParam apiParam : apiMethodDoc.getPathParams()) { - parameters = getStringParams(apiParam, false); + parameters = this.getStringParams(apiParam, false); parameters.put("type", DocUtil.javaTypeToOpenApiTypeConvert(apiParam.getType())); parameters.put("in", "path"); parametersList.add(parameters); } for (ApiParam apiParam : apiMethodDoc.getQueryParams()) { if (apiParam.getType().equals(ParamTypeConstants.PARAM_TYPE_ARRAY) || apiParam.isHasItems()) { - parameters = getStringParams(apiParam, false); + parameters = this.getStringParams(apiParam, false); parameters.put("type", ParamTypeConstants.PARAM_TYPE_ARRAY); - parameters.put("items", getStringParams(apiParam, true)); + parameters.put("items", this.getStringParams(apiParam, true)); parametersList.add(parameters); } else { - parameters = getStringParams(apiParam, false); + parameters = this.getStringParams(apiParam, false); parameters.put("type", DocUtil.javaTypeToOpenApiTypeConvert(apiParam.getType())); parametersList.add(parameters); } @@ -272,7 +283,7 @@ else if (desc.contains("string")) { @Override public Map buildComponentsSchema(ApiSchema apiSchema) { - return buildComponentData(apiSchema); + return this.buildComponentData(apiSchema); } } diff --git a/src/main/java/com/ly/doc/builder/rpc/RpcAdocBuilder.java b/src/main/java/com/ly/doc/builder/rpc/RpcAdocBuilder.java index 78c3bc9f..4cd1e0e3 100644 --- a/src/main/java/com/ly/doc/builder/rpc/RpcAdocBuilder.java +++ b/src/main/java/com/ly/doc/builder/rpc/RpcAdocBuilder.java @@ -29,12 +29,21 @@ import java.util.List; /** + * Build Rpc Asciidoc + * * @author yu 2020/5/17. + * @since 1.8.7 */ public class RpcAdocBuilder { + /** + * RpcApi.adoc + */ private static final String API_EXTENSION = "RpcApi.adoc"; + /** + * rpc-index.adoc + */ private static final String INDEX_DOC = "rpc-index.adoc"; /** diff --git a/src/main/java/com/ly/doc/builder/rpc/RpcHtmlBuilder.java b/src/main/java/com/ly/doc/builder/rpc/RpcHtmlBuilder.java index abf5e61b..94f66741 100644 --- a/src/main/java/com/ly/doc/builder/rpc/RpcHtmlBuilder.java +++ b/src/main/java/com/ly/doc/builder/rpc/RpcHtmlBuilder.java @@ -29,7 +29,10 @@ import java.util.List; /** + * RPC HTML builder + * * @author yu 2020/5/17. + * @since 1.8.7 */ public class RpcHtmlBuilder { diff --git a/src/main/java/com/ly/doc/constants/ApiReqParamInTypeEnum.java b/src/main/java/com/ly/doc/constants/ApiReqParamInTypeEnum.java index 61cd88a0..d0897018 100644 --- a/src/main/java/com/ly/doc/constants/ApiReqParamInTypeEnum.java +++ b/src/main/java/com/ly/doc/constants/ApiReqParamInTypeEnum.java @@ -21,6 +21,8 @@ package com.ly.doc.constants; /** + * ApiReqParamInTypeEnum + * * @author chen qi 2021-07-15 10:55 **/ public enum ApiReqParamInTypeEnum { @@ -40,12 +42,23 @@ public enum ApiReqParamInTypeEnum { */ PATH("path"); + /** + * value + */ private final String value; + /** + * constructor + * @param value value + */ ApiReqParamInTypeEnum(String value) { this.value = value; } + /** + * get value + * @return value + */ public String getValue() { return value; } diff --git a/src/main/java/com/ly/doc/constants/ComponentTypeEnum.java b/src/main/java/com/ly/doc/constants/ComponentTypeEnum.java index a4b78127..1ade667c 100644 --- a/src/main/java/com/ly/doc/constants/ComponentTypeEnum.java +++ b/src/main/java/com/ly/doc/constants/ComponentTypeEnum.java @@ -24,6 +24,8 @@ import org.apache.commons.lang3.StringUtils; /** + * ComponentTypeEnum + * * @author xingzi Date 2023/9/10 14:47 */ public enum ComponentTypeEnum { @@ -46,6 +48,12 @@ public enum ComponentTypeEnum { */ private final String componentType; + /** + * get random name + * @param componentTypeEnum componentTypeEnum + * @param apiMethodDoc apiMethodDoc + * @return random name + */ public static String getRandomName(ComponentTypeEnum componentTypeEnum, ApiMethodDoc apiMethodDoc) { if (componentTypeEnum.equals(RANDOM)) { return apiMethodDoc.getUrl(); @@ -53,6 +61,10 @@ public static String getRandomName(ComponentTypeEnum componentTypeEnum, ApiMetho return StringUtils.EMPTY; } + /** + * get componentType + * @return componentType + */ public String getComponentType() { return componentType; } diff --git a/src/main/java/com/ly/doc/constants/DocLanguage.java b/src/main/java/com/ly/doc/constants/DocLanguage.java index 479e002f..e22daa9b 100644 --- a/src/main/java/com/ly/doc/constants/DocLanguage.java +++ b/src/main/java/com/ly/doc/constants/DocLanguage.java @@ -41,10 +41,18 @@ public enum DocLanguage { */ public final String code; + /** + * constructor + * @param code language code + */ DocLanguage(String code) { this.code = code; } + /** + * get language code + * @return language code + */ public String getCode() { return this.code; } diff --git a/src/main/java/com/ly/doc/constants/DocTags.java b/src/main/java/com/ly/doc/constants/DocTags.java index 3f21c1f8..c90ec8d0 100644 --- a/src/main/java/com/ly/doc/constants/DocTags.java +++ b/src/main/java/com/ly/doc/constants/DocTags.java @@ -21,6 +21,8 @@ package com.ly.doc.constants; /** + * Doc tags + * * @author yu 2019/9/13. */ public interface DocTags { @@ -110,6 +112,9 @@ public interface DocTags { */ String IGNORE_RESPONSE_BODY_ADVICE = "ignoreResponseBodyAdvice"; + /** + * ignore RequestBodyAdvice + */ String IGNORE_REQUEST_BODY_ADVICE = "ignoreRequestBodyAdvice"; /** diff --git a/src/main/java/com/ly/doc/constants/DubboAnnotationConstants.java b/src/main/java/com/ly/doc/constants/DubboAnnotationConstants.java index 8d171a6a..637e5e27 100644 --- a/src/main/java/com/ly/doc/constants/DubboAnnotationConstants.java +++ b/src/main/java/com/ly/doc/constants/DubboAnnotationConstants.java @@ -27,18 +27,26 @@ */ public interface DubboAnnotationConstants { + /** + * dubbo service annotation {@code org.apache.dubbo.config.annotation.Service} + */ String SERVICE = "org.apache.dubbo.config.annotation.Service"; /** + * dubbo service {@code org.apache.dubbo.config.annotation.DubboService} * @since dubbo 2.7.7 */ String DUBBO_SERVICE = "org.apache.dubbo.config.annotation.DubboService"; /** - * support ali dubbo + * support ali dubbo {@code com.alibaba.dubbo.config.annotation.Service} */ String ALI_DUBBO_SERVICE = "com.alibaba.dubbo.config.annotation.Service"; + /** + * dubbo swagger. + * {@code org.apache.dubbo.rpc.protocol.rest.integration.swagger.DubboSwaggerApiListingResource} + */ String DUBBO_SWAGGER = "org.apache.dubbo.rpc.protocol.rest.integration.swagger.DubboSwaggerApiListingResource"; } diff --git a/src/main/java/com/ly/doc/constants/FrameworkEnum.java b/src/main/java/com/ly/doc/constants/FrameworkEnum.java index c608aab7..94b282cc 100644 --- a/src/main/java/com/ly/doc/constants/FrameworkEnum.java +++ b/src/main/java/com/ly/doc/constants/FrameworkEnum.java @@ -74,11 +74,21 @@ public enum FrameworkEnum { */ private final String className; + /** + * Constructor + * @param framework framework name + * @param className class name + */ FrameworkEnum(String framework, String className) { this.framework = framework; this.className = className; } + /** + * Get class name by framework. + * @param framework framework name + * @return class name + */ public static String getClassNameByFramework(String framework) { String className = ""; if (StringUtil.isEmpty(framework)) { @@ -101,10 +111,18 @@ public static String allFramework() { return Arrays.stream(FrameworkEnum.values()).map(FrameworkEnum::getFramework).collect(Collectors.joining(",")); } + /** + * Get framework name. + * @return framework name + */ public String getFramework() { return framework; } + /** + * Get class name. + * @return class name + */ public String getClassName() { return className; } diff --git a/src/main/java/com/ly/doc/constants/GrpcMethodTypeEnum.java b/src/main/java/com/ly/doc/constants/GrpcMethodTypeEnum.java index 61aba783..b178290b 100644 --- a/src/main/java/com/ly/doc/constants/GrpcMethodTypeEnum.java +++ b/src/main/java/com/ly/doc/constants/GrpcMethodTypeEnum.java @@ -81,10 +81,18 @@ public String getType() { return type; } + /** + * Request Streaming + * @return Request Streaming + */ public boolean isRequestStreaming() { return requestStreaming; } + /** + * Response Streaming + * @return Response Streaming + */ public boolean isResponseStreaming() { return responseStreaming; } diff --git a/src/main/java/com/ly/doc/constants/HighLightJsConstants.java b/src/main/java/com/ly/doc/constants/HighLightJsConstants.java index c0a8377e..861e56a7 100644 --- a/src/main/java/com/ly/doc/constants/HighLightJsConstants.java +++ b/src/main/java/com/ly/doc/constants/HighLightJsConstants.java @@ -25,14 +25,29 @@ */ public interface HighLightJsConstants { + /** + * HighLightJs CSS URL Format + */ String HIGH_LIGHT_CSS_URL_FORMAT = "https://cdn.bootcdn.net/ajax/libs/highlight.js/10.3.2/styles/%s.min.css"; + /** + * Default Style + */ String HIGH_LIGHT_DEFAULT_STYLE = "xt256"; + /** + * Highlight.js CSS Default + */ String HIGH_LIGHT_CSS_DEFAULT = "xt256.min.css"; + /** + * Highlight.js CSS RandomLight + */ String HIGH_LIGHT_CSS_RANDOM_LIGHT = "randomLight"; + /** + * Highlight.js CSS RandomDark + */ String HIGH_LIGHT_CSS_RANDOM_DARK = "randomDark"; } diff --git a/src/main/java/com/ly/doc/constants/HighlightStyle.java b/src/main/java/com/ly/doc/constants/HighlightStyle.java index c965c9e5..2ba0ce0a 100644 --- a/src/main/java/com/ly/doc/constants/HighlightStyle.java +++ b/src/main/java/com/ly/doc/constants/HighlightStyle.java @@ -20,52 +20,68 @@ */ package com.ly.doc.constants; -import java.util.Arrays; +import com.power.common.util.StringUtil; + import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.Random; - -import com.power.common.util.StringUtil; +import java.util.stream.Collectors; +import java.util.stream.Stream; /** + * Highlight style + * * @author jitmit 2020/11/16 */ public class HighlightStyle { + /** + * Default style + */ public static final String DEFAULT_STYLE = "github"; + /** + * Dark style + */ private static final List DARK_STYLE; + /** + * Light style + */ private static final List LIGHT_STYLE; /** * key is style,value is color */ - private static final Map BACKGROUND = new HashMap<>(); + private static final Map BACKGROUND = new HashMap<>(76); static { - LIGHT_STYLE = Arrays.asList(DEFAULT_STYLE, "a11y-light", "arduino-light", "ascetic", "atelier-cave-light", - "atelier-dune-light", "atelier-estuary-light", "atelier-forest-light", "atelier-heath-light", - "atelier-lakeside-light", "atelier-plateau-light", "atelier-savanna-light", "atelier-seaside-light", - "atelier-sulphurpool-light", "atom-one-light", "color-brewer", "docco", "github-gist", "googlecode", - "grayscale", "gruvbox-light", "idea", "isbl-editor-light", "kimbie.light", "lightfair", "magula", - "mono-blue", "nnfx", "paraiso-light", "purebasic", "qtcreator_light", "routeros", "school-book", - "solarized-light", "tomorrow", "vs", "xcode"); + LIGHT_STYLE = Stream + .of(DEFAULT_STYLE, "a11y-light", "arduino-light", "ascetic", "atelier-cave-light", "atelier-dune-light", + "atelier-estuary-light", "atelier-forest-light", "atelier-heath-light", "atelier-lakeside-light", + "atelier-plateau-light", "atelier-savanna-light", "atelier-seaside-light", + "atelier-sulphurpool-light", "atom-one-light", "color-brewer", "docco", "github-gist", "googlecode", + "grayscale", "gruvbox-light", "idea", "isbl-editor-light", "kimbie.light", "lightfair", "magula", + "mono-blue", "nnfx", "paraiso-light", "purebasic", "qtcreator_light", "routeros", "school-book", + "solarized-light", "tomorrow", "vs", "xcode") + .collect(Collectors.toList()); } static { - DARK_STYLE = Arrays.asList("a11y-dark", "agate", "an-old-hope", "androidstudio", "arta", "atelier-cave-dark", - "atelier-dune-dark", "atelier-estuary-dark", "atelier-forest-dark", "atelier-heath-dark", - "atelier-lakeside-dark", "atelier-plateau-dark", "atelier-savanna-dark", "atelier-seaside-dark", - "atelier-sulphurpool-dark", "atom-one-dark-reasonable", "atom-one-dark", "brown-paper", "codepen-embed", - "darcula", "dark", "default", "dracula", "far", "foundation", "gml", "gradient-dark", "gruvbox-dark", - "hopscotch", "hybrid", "ir-black", "isbl-editor-dark", "kimbie.dark", "lioshi", "monokai", - "monokai-sublime", "night-owl", "nnfx-dark", "nord", "obsidian", "ocean", "paraiso-dark", "pojoaque", - "qtcreator_dark", "railscasts", "rainbow", "shades-of-purple", "solarized-dark", "srcery", "sunburst", - "tomorrow-night", "tomorrow-night-blue", "tomorrow-night-bright", "tomorrow-night-eighties", "vs2015", - "xt256", "zenburn"); + DARK_STYLE = Stream + .of("a11y-dark", "agate", "an-old-hope", "androidstudio", "arta", "atelier-cave-dark", "atelier-dune-dark", + "atelier-estuary-dark", "atelier-forest-dark", "atelier-heath-dark", "atelier-lakeside-dark", + "atelier-plateau-dark", "atelier-savanna-dark", "atelier-seaside-dark", "atelier-sulphurpool-dark", + "atom-one-dark-reasonable", "atom-one-dark", "brown-paper", "codepen-embed", "darcula", "dark", + "default", "dracula", "far", "foundation", "gml", "gradient-dark", "gruvbox-dark", "hopscotch", + "hybrid", "ir-black", "isbl-editor-dark", "kimbie.dark", "lioshi", "monokai", "monokai-sublime", + "night-owl", "nnfx-dark", "nord", "obsidian", "ocean", "paraiso-dark", "pojoaque", "qtcreator_dark", + "railscasts", "rainbow", "shades-of-purple", "solarized-dark", "srcery", "sunburst", + "tomorrow-night", "tomorrow-night-blue", "tomorrow-night-bright", "tomorrow-night-eighties", + "vs2015", "xt256", "zenburn") + .collect(Collectors.toList()); } static { @@ -180,6 +196,11 @@ public static String randomAll(Random random) { } } + /** + * Get background color + * @param style Highlight style + * @return String of background color + */ public static String getBackgroundColor(String style) { String color = BACKGROUND.get(style); if (StringUtil.isNotEmpty(color)) { diff --git a/src/main/java/com/ly/doc/constants/JAXRSAnnotations.java b/src/main/java/com/ly/doc/constants/JAXRSAnnotations.java index 70fbfd6b..780b1109 100644 --- a/src/main/java/com/ly/doc/constants/JAXRSAnnotations.java +++ b/src/main/java/com/ly/doc/constants/JAXRSAnnotations.java @@ -91,6 +91,9 @@ public final class JAXRSAnnotations { */ public static final String JAXB_HEAD_FULLY = "javax.ws.rs.HEAD"; + /** + * private constructor + */ private JAXRSAnnotations() { throw new IllegalStateException("Utility class"); } diff --git a/src/main/java/com/ly/doc/constants/JSRAnnotationConstants.java b/src/main/java/com/ly/doc/constants/JSRAnnotationConstants.java index ab4cc56c..02ddd839 100644 --- a/src/main/java/com/ly/doc/constants/JSRAnnotationConstants.java +++ b/src/main/java/com/ly/doc/constants/JSRAnnotationConstants.java @@ -21,6 +21,8 @@ package com.ly.doc.constants; /** + * JSR303 Annotation Constants + * * @author yu 2024/6/7 */ public interface JSRAnnotationConstants { diff --git a/src/main/java/com/ly/doc/constants/JSRAnnotationPropConstants.java b/src/main/java/com/ly/doc/constants/JSRAnnotationPropConstants.java index 4e265065..801ea13d 100644 --- a/src/main/java/com/ly/doc/constants/JSRAnnotationPropConstants.java +++ b/src/main/java/com/ly/doc/constants/JSRAnnotationPropConstants.java @@ -22,14 +22,25 @@ package com.ly.doc.constants; /** + * JSR annotation property constants + * * @author yu 2024/6/7 */ public interface JSRAnnotationPropConstants { + /** + * max property + */ String MAX_PROP = "max"; + /** + * min property + */ String MIN_PROP = "min"; + /** + * value property + */ String VALUE = "value"; } diff --git a/src/main/java/com/ly/doc/constants/JakartaJaxrsAnnotations.java b/src/main/java/com/ly/doc/constants/JakartaJaxrsAnnotations.java index 35c6858d..50a5ce13 100644 --- a/src/main/java/com/ly/doc/constants/JakartaJaxrsAnnotations.java +++ b/src/main/java/com/ly/doc/constants/JakartaJaxrsAnnotations.java @@ -31,45 +31,63 @@ public final class JakartaJaxrsAnnotations { /** - * JAX-RS@DefaultValue + * JAX-RS @DefaultValue */ public static final String JAX_DEFAULT_VALUE_FULLY = "jakarta.ws.rs.DefaultValue"; + /** + * JAX-RS @DefaultValue + */ public static final String JAX_DEFAULT_VALUE = "DefaultValue"; /** - * JAX-RS@HeaderParam + * JAX-RS @HeaderParam */ public static final String JAX_HEADER_PARAM_FULLY = "jakarta.ws.rs.HeaderParam"; + /** + * JAX-RS @HeaderParam + */ public static final String JAX_HEADER_PARAM = "HeaderParam"; /** - * JAX-RS@PathParam + * JAX-RS @PathParam */ public static final String JAX_PATH_PARAM_FULLY = "jakarta.ws.rs.PathParam"; + /** + * JAX-RS @PathParam + */ public static final String JAX_PATH_PARAM = "PathParam"; /** - * JAX-RS@PATH + * JAX-RS @Path */ public static final String JAX_PATH_FULLY = "jakarta.ws.rs.Path"; + /** + * JAX-RS @Path + */ public static final String JAX_PATH = "Path"; /** - * JAX-RS@Produces + * JAX-RS @Produces */ public static final String JAX_PRODUCES_FULLY = "jakarta.ws.rs.Produces"; + /** + * JAX-RS @Produces + */ public static final String JAX_PRODUCES = "Produces"; /** - * JAX-RS@Consumes + * JAX-RS @Consumes */ public static final String JAX_CONSUMES_FULLY = "jakarta.ws.rs.Consumes"; + /** + * JAX-RS @Consumes + */ public static final String JAX_CONSUMES = "Consumes"; /** @@ -127,6 +145,9 @@ public final class JakartaJaxrsAnnotations { */ public static final String JAX_HEAD_FULLY = "jakarta.ws.rs.HEAD"; + /** + * private constructor + */ private JakartaJaxrsAnnotations() { throw new IllegalStateException("Utility class"); } diff --git a/src/main/java/com/ly/doc/constants/JsonPropertyAnnotationAccessConstants.java b/src/main/java/com/ly/doc/constants/JsonPropertyAnnotationAccessConstants.java index 11b235bc..315bb58c 100644 --- a/src/main/java/com/ly/doc/constants/JsonPropertyAnnotationAccessConstants.java +++ b/src/main/java/com/ly/doc/constants/JsonPropertyAnnotationAccessConstants.java @@ -1,14 +1,25 @@ package com.ly.doc.constants; /** + * JsonProperty Annotation Access Constants + * * @author yu 2024/6/7 */ public interface JsonPropertyAnnotationAccessConstants { + /** + * JsonProperty.Access.READ_WRITE + */ String JSON_PROPERTY_READ_WRITE = "JsonProperty.Access.READ_WRITE"; + /** + * JsonProperty.Access.READ_ONLY + */ String JSON_PROPERTY_READ_ONLY = "JsonProperty.Access.READ_ONLY"; + /** + * JsonProperty.Access.WRITE_ONLY + */ String JSON_PROPERTY_WRITE_ONLY = "JsonProperty.Access.WRITE_ONLY"; } diff --git a/src/main/java/com/ly/doc/constants/SolonAnnotations.java b/src/main/java/com/ly/doc/constants/SolonAnnotations.java index f5fea671..1d6c6619 100644 --- a/src/main/java/com/ly/doc/constants/SolonAnnotations.java +++ b/src/main/java/com/ly/doc/constants/SolonAnnotations.java @@ -22,6 +22,8 @@ package com.ly.doc.constants; /** + * Solon Annotations + * * @author noear 2022/2/19 created */ public interface SolonAnnotations { diff --git a/src/main/java/com/ly/doc/constants/SolonRequestAnnotationsEnum.java b/src/main/java/com/ly/doc/constants/SolonRequestAnnotationsEnum.java index c059da14..75d8b432 100644 --- a/src/main/java/com/ly/doc/constants/SolonRequestAnnotationsEnum.java +++ b/src/main/java/com/ly/doc/constants/SolonRequestAnnotationsEnum.java @@ -24,6 +24,8 @@ import java.util.List; /** + * Solon Request Annotation Enum + * * @author yu 2019/12/20. */ public enum SolonRequestAnnotationsEnum { diff --git a/src/main/java/com/ly/doc/constants/SpringMvcAnnotations.java b/src/main/java/com/ly/doc/constants/SpringMvcAnnotations.java index 9229c5d2..957297f3 100644 --- a/src/main/java/com/ly/doc/constants/SpringMvcAnnotations.java +++ b/src/main/java/com/ly/doc/constants/SpringMvcAnnotations.java @@ -21,6 +21,9 @@ package com.ly.doc.constants; /** + * + * Spring MVC Annotations + * * @author yu 2019/12/21. */ public interface SpringMvcAnnotations { diff --git a/src/main/java/com/ly/doc/constants/SpringMvcRequestAnnotationsEnum.java b/src/main/java/com/ly/doc/constants/SpringMvcRequestAnnotationsEnum.java index a69975d7..96a66c08 100644 --- a/src/main/java/com/ly/doc/constants/SpringMvcRequestAnnotationsEnum.java +++ b/src/main/java/com/ly/doc/constants/SpringMvcRequestAnnotationsEnum.java @@ -87,10 +87,18 @@ public enum SpringMvcRequestAnnotationsEnum { */ private final String value; + /** + * SpringMvc RequestAnnotation constructor + * @param value SpringMvc RequestAnnotation value + */ SpringMvcRequestAnnotationsEnum(String value) { this.value = value; } + /** + * get SpringMvc RequestAnnotation list + * @return SpringMvc RequestAnnotation list + */ public static List listSpringMvcRequestAnnotations() { List annotations = new ArrayList<>(); for (SpringMvcRequestAnnotationsEnum annotation : SpringMvcRequestAnnotationsEnum.values()) { diff --git a/src/main/java/com/ly/doc/constants/TemplateVariable.java b/src/main/java/com/ly/doc/constants/TemplateVariable.java index eb42ce1f..ce12e034 100644 --- a/src/main/java/com/ly/doc/constants/TemplateVariable.java +++ b/src/main/java/com/ly/doc/constants/TemplateVariable.java @@ -21,6 +21,8 @@ package com.ly.doc.constants; /** + * Template Variable. + * * @author yu 2019/9/21. */ public enum TemplateVariable { @@ -211,10 +213,18 @@ public enum TemplateVariable { */ private final String variable; + /** + * constructor + * @param variable variable + */ TemplateVariable(String variable) { this.variable = variable; } + /** + * get variable + * @return variable + */ public String getVariable() { return this.variable; } diff --git a/src/main/java/com/ly/doc/constants/TornaConstants.java b/src/main/java/com/ly/doc/constants/TornaConstants.java index f4f066dc..f69252e0 100644 --- a/src/main/java/com/ly/doc/constants/TornaConstants.java +++ b/src/main/java/com/ly/doc/constants/TornaConstants.java @@ -20,57 +20,98 @@ */ package com.ly.doc.constants; -import java.io.IOException; -import java.net.URLEncoder; -import java.security.MessageDigest; -import java.util.ArrayList; -import java.util.Collections; -import java.util.HashMap; -import java.util.List; -import java.util.Map; -import java.util.Set; - import com.google.gson.Gson; import com.google.gson.GsonBuilder; import com.ly.doc.model.ApiConfig; import com.power.common.util.DateTimeUtil; - import org.apache.commons.lang3.StringUtils; +import java.io.IOException; +import java.net.URLEncoder; +import java.security.MessageDigest; +import java.util.*; +import java.util.logging.Logger; + /** + * Torna Constants + * * @author xingzi 2020/2/2 */ public class TornaConstants { + /** + * logger + */ + private static final Logger logger = Logger.getLogger(TornaConstants.class.getName()); + + /** + * id + */ public static final String ID = "id"; + /** + * code + */ public static final String CODE = "code"; + /** + * message + */ public static final String MESSAGE = "msg"; + /** + * data + */ public static final String DATA = "data"; + /** + * success code + */ public static final String SUCCESS_CODE = "0"; + /** + * default group code + */ public static final String DEFAULT_GROUP_CODE = "default"; + /** + * yes + */ public static final String YES = "1"; + /** + * no + */ public static final String NO = "0"; + /** + * array + */ public static final String ARRAY = "array"; + /** + * create category + */ public static final String CATEGORY_CREATE = "doc.category.create"; + /** + * push + */ public static final String PUSH = "doc.push"; + /** + * enum push + */ public static final String ENUM_PUSH = "enum.batch.push"; /** - * torna文件数组类型 + * torna file array type */ public static final String PARAM_TYPE_FILE_ARRAY = "file[]"; + /** + * Gson + */ public static final Gson GSON = new GsonBuilder().setPrettyPrinting().create(); /** @@ -98,7 +139,7 @@ public static Map buildParams(String name, String data, ApiConfi return param; } catch (IOException e) { - e.printStackTrace(); + logger.warning(e.getMessage()); } return param; } diff --git a/src/main/java/com/ly/doc/constants/ValidatorAnnotations.java b/src/main/java/com/ly/doc/constants/ValidatorAnnotations.java index a66fa68d..1c068194 100644 --- a/src/main/java/com/ly/doc/constants/ValidatorAnnotations.java +++ b/src/main/java/com/ly/doc/constants/ValidatorAnnotations.java @@ -21,6 +21,8 @@ package com.ly.doc.constants; /** + * Validator Annotations. + * * @author yu 2019/12/22. * @see JSRAnnotationConstants */ diff --git a/src/main/java/com/ly/doc/extension/dict/DictionaryValuesResolver.java b/src/main/java/com/ly/doc/extension/dict/DictionaryValuesResolver.java index 281e4210..3ad706d8 100644 --- a/src/main/java/com/ly/doc/extension/dict/DictionaryValuesResolver.java +++ b/src/main/java/com/ly/doc/extension/dict/DictionaryValuesResolver.java @@ -26,6 +26,8 @@ import java.util.Collections; /** + * dictionary values resolver + * * @author 吴垚 * @see issues-338 */ diff --git a/src/main/java/com/ly/doc/extension/json/PropertyNameHelper.java b/src/main/java/com/ly/doc/extension/json/PropertyNameHelper.java index 9adb4236..f8e36420 100644 --- a/src/main/java/com/ly/doc/extension/json/PropertyNameHelper.java +++ b/src/main/java/com/ly/doc/extension/json/PropertyNameHelper.java @@ -1,33 +1,87 @@ +/* + * Copyright (C) 2018-2024 smart-doc + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ package com.ly.doc.extension.json; -import java.util.List; - import com.ly.doc.constants.DocAnnotationConstants; import com.power.common.util.StringUtil; import com.thoughtworks.qdox.model.JavaAnnotation; +import java.util.List; + /** - * @author xingzi Date 2022/9/17 13:32 + * PropertyNameHelper - Utility class for translating property naming strategies. This + * class is primarily used to convert annotation-defined naming strategies into actual + * naming strategies used in the code. It mainly supports several Jackson naming strategy + * conversions. + * + * @author xingzi Date: 2022/9/17 13:32 */ public class PropertyNameHelper { + /** + * Jackson's lowerCamelCase naming strategy + */ public static final String JACKSON_LOWER_CAMEL_CASE = "lowercamel"; + /** + * Jackson's UPPER_CAMEL_CASE naming strategy + */ public static final String JACKSON_UPPER_CAMEL_CASE = "uppercamel"; + /** + * Jackson's snake_case naming strategy + */ public static final String JACKSON_SNAKE_CASE = "snake"; + /** + * Jackson's UPPER_SNAKE_CASE naming strategy + */ public static final String JACKSON_UPPER_SNAKE_CASE = "uppersnake"; + /** + * Jackson's lower naming strategy + */ public static final String JACKSON_LOWER_CASE = "lower"; + /** + * Jackson's kebab_case naming strategy + */ public static final String JACKSON_KEBAB_CASE = "kebab"; + /** + * Jackson's lower.dot.case naming strategy + */ public static final String JACKSON_LOWER_DOT_CASE = "lowerdot"; + /** + * Private constructor to prevent instantiation + */ private PropertyNameHelper() { } + /** + * Translates Java annotations to property naming strategies. + * @param javaAnnotations List of Java annotations on a property + * @return The property naming strategy, or null if no matching strategy is found + */ public static PropertyNamingStrategies.NamingBase translate(List javaAnnotations) { for (JavaAnnotation annotation : javaAnnotations) { String simpleAnnotationName = annotation.getType().getValue(); @@ -41,6 +95,12 @@ public static PropertyNamingStrategies.NamingBase translate(List return null; } + /** + * Translates the value of a Jackson naming strategy annotation to the corresponding + * property naming strategy. + * @param annotationValue The value of the annotation + * @return The corresponding property naming strategy, or null if no match is found + */ private static PropertyNamingStrategies.NamingBase jackSonTranslate(String annotationValue) { if (StringUtil.isEmpty(annotationValue)) { return null; diff --git a/src/main/java/com/ly/doc/extension/json/PropertyNamingStrategies.java b/src/main/java/com/ly/doc/extension/json/PropertyNamingStrategies.java index a80f91bf..ae2d9b2d 100644 --- a/src/main/java/com/ly/doc/extension/json/PropertyNamingStrategies.java +++ b/src/main/java/com/ly/doc/extension/json/PropertyNamingStrategies.java @@ -1,10 +1,30 @@ - +/* + * Copyright (C) 2018-2024 smart-doc + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ package com.ly.doc.extension.json; /** - * copy from jackson and singleton instances. . + * copy from jackson and singleton instances. * + * @see PropertyNamingStrategies. * @author xingzi */ public abstract class PropertyNamingStrategies implements java.io.Serializable { diff --git a/src/main/java/com/ly/doc/filter/BoxReturnFilter.java b/src/main/java/com/ly/doc/filter/BoxReturnFilter.java index 87c6e041..c6f44bdb 100644 --- a/src/main/java/com/ly/doc/filter/BoxReturnFilter.java +++ b/src/main/java/com/ly/doc/filter/BoxReturnFilter.java @@ -20,19 +20,23 @@ */ package com.ly.doc.filter; -import java.util.HashSet; -import java.util.Set; - -import com.ly.doc.constants.DocGlobalConstants; import com.ly.doc.constants.JavaTypeConstants; import com.ly.doc.model.ApiReturn; import com.ly.doc.utils.DocClassUtil; +import java.util.HashSet; +import java.util.Set; + /** + * Box Return Filter + * * @author yu 2020/4/17. */ public class BoxReturnFilter implements ReturnTypeFilter { + /** + * Box Return Type + */ private static final Set TYPE_SET = new HashSet<>(); static { diff --git a/src/main/java/com/ly/doc/filter/ReturnTypeProcessor.java b/src/main/java/com/ly/doc/filter/ReturnTypeProcessor.java index 56c6d55c..8589f5a5 100644 --- a/src/main/java/com/ly/doc/filter/ReturnTypeProcessor.java +++ b/src/main/java/com/ly/doc/filter/ReturnTypeProcessor.java @@ -20,19 +20,27 @@ */ package com.ly.doc.filter; +import com.ly.doc.model.ApiReturn; + import java.util.ArrayList; import java.util.List; import java.util.Objects; -import com.ly.doc.model.ApiReturn; - /** + * Return Type Processor + * * @author yu 2020/4/17. */ public class ReturnTypeProcessor { - private List filters = new ArrayList<>(); + /** + * return type filter + */ + private final List filters = new ArrayList<>(); + /** + * return type + */ private String typeName; public String getTypeName() { @@ -43,6 +51,10 @@ public void setTypeName(String typeName) { this.typeName = typeName; } + /** + * process return type + * @return ApiReturn + */ public ApiReturn process() { filters.add(new WebFluxReturnFilter()); filters.add(new BoxReturnFilter()); diff --git a/src/main/java/com/ly/doc/filter/WebFluxReturnFilter.java b/src/main/java/com/ly/doc/filter/WebFluxReturnFilter.java index 5ee42cc2..9300bc88 100644 --- a/src/main/java/com/ly/doc/filter/WebFluxReturnFilter.java +++ b/src/main/java/com/ly/doc/filter/WebFluxReturnFilter.java @@ -20,15 +20,19 @@ */ package com.ly.doc.filter; -import com.ly.doc.constants.DocGlobalConstants; import com.ly.doc.constants.JavaTypeConstants; import com.ly.doc.model.ApiReturn; /** + * WebFlux Return Filter + * * @author yu 2020/4/17. */ public class WebFluxReturnFilter implements ReturnTypeFilter { + /** + * Flux + */ private static final String FLUX = "reactor.core.publisher.Flux"; @Override diff --git a/src/main/java/com/ly/doc/handler/ICustomJavaMethodHandler.java b/src/main/java/com/ly/doc/handler/ICustomJavaMethodHandler.java index 64e2dd4e..0c2d07ef 100644 --- a/src/main/java/com/ly/doc/handler/ICustomJavaMethodHandler.java +++ b/src/main/java/com/ly/doc/handler/ICustomJavaMethodHandler.java @@ -33,6 +33,12 @@ @FunctionalInterface public interface ICustomJavaMethodHandler { + /** + * handle customized operation for {@link DocJavaMethod}. + * @param cls JavaClass + * @param methodList DocJavaMethod list + * @return {@code List} + */ List apply(JavaClass cls, List methodList); } diff --git a/src/main/java/com/ly/doc/handler/IHeaderHandler.java b/src/main/java/com/ly/doc/handler/IHeaderHandler.java index c0746744..91944cca 100644 --- a/src/main/java/com/ly/doc/handler/IHeaderHandler.java +++ b/src/main/java/com/ly/doc/handler/IHeaderHandler.java @@ -20,33 +20,37 @@ */ package com.ly.doc.handler; -import java.util.ArrayList; -import java.util.Collection; -import java.util.LinkedList; -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.stream.Collectors; -import java.util.stream.Stream; - -import com.ly.doc.model.ApiReqParam; -import com.ly.doc.utils.DocUtil; -import com.power.common.util.StringUtil; import com.ly.doc.builder.ProjectDocConfigBuilder; import com.ly.doc.constants.DocTags; +import com.ly.doc.model.ApiReqParam; import com.ly.doc.model.annotation.HeaderAnnotation; import com.ly.doc.utils.DocClassUtil; +import com.ly.doc.utils.DocUtil; import com.ly.doc.utils.JavaFieldUtil; +import com.power.common.util.StringUtil; import com.thoughtworks.qdox.model.JavaAnnotation; import com.thoughtworks.qdox.model.JavaMethod; import com.thoughtworks.qdox.model.JavaParameter; import com.thoughtworks.qdox.model.JavaType; +import java.util.*; +import java.util.stream.Collectors; +import java.util.stream.Stream; + /** + * Header Handler + * * @author yu3.sun on 2022/8/30 */ public interface IHeaderHandler { + /** + * Handle header + * @param method JavaMethod + * @param projectBuilder ProjectDocConfigBuilder + * @return {@code List} + */ + @SuppressWarnings("unchecked") default List handle(JavaMethod method, ProjectDocConfigBuilder projectBuilder) { Map constantsMap = projectBuilder.getConstantsMap(); List mappingHeaders = new ArrayList<>(); @@ -63,7 +67,7 @@ default List handle(JavaMethod method, ProjectDocConfigBuilder proj processMappingHeaders(mappingHeader, mappingHeaders); continue; } - List headers = (LinkedList) headersObject; + List headers = (LinkedList) headersObject; for (String str : headers) { String header = StringUtil.removeQuotes(str); if (header.startsWith("!")) { @@ -144,6 +148,11 @@ default List handle(JavaMethod method, ProjectDocConfigBuilder proj .collect(Collectors.toList()); } + /** + * process mapping headers + * @param header header + * @param mappingHeaders mapping headers + */ default void processMappingHeaders(String header, List mappingHeaders) { if (header.contains("!=")) { String headerName = header.substring(0, header.indexOf("!")); diff --git a/src/main/java/com/ly/doc/handler/IRequestMappingHandler.java b/src/main/java/com/ly/doc/handler/IRequestMappingHandler.java index 64108962..57f8d3ee 100644 --- a/src/main/java/com/ly/doc/handler/IRequestMappingHandler.java +++ b/src/main/java/com/ly/doc/handler/IRequestMappingHandler.java @@ -39,10 +39,22 @@ import java.util.Objects; /** + * RequestMapping Handler Interface Responsible for handling and formatting controller + * request mapping information. + * * @author yu3.sun on 2022/10/1 */ public interface IRequestMappingHandler { + /** + * Formats the request mapping data. Generates and formats the URL and short URL for + * the given request mapping object. + * @param projectBuilder Project documentation configuration builder containing + * project-related configurations + * @param controllerBaseUrl Base URL of the controller + * @param requestMapping RequestMapping object to be formatted + * @return Formatted RequestMapping object + */ default RequestMapping formatMappingData(ProjectDocConfigBuilder projectBuilder, String controllerBaseUrl, RequestMapping requestMapping) { String shortUrl = requestMapping.getShortUrl(); @@ -66,16 +78,21 @@ default RequestMapping formatMappingData(ProjectDocConfigBuilder projectBuilder, return requestMapping; } + /** + * Retrieves all annotations from a method, including those inherited from interfaces. + * @param method The JavaMethod object for which annotations are to be retrieved + * @return A list of JavaAnnotation objects representing the annotations on the method + */ default List getAnnotations(JavaMethod method) { List annotations = new ArrayList<>(); - // add interface method annotations + // Add interface method annotations List interfaces = method.getDeclaringClass().getInterfaces(); if (CollectionUtil.isNotEmpty(interfaces)) { for (JavaClass interfaceClass : interfaces) { JavaMethod interfaceMethod = interfaceClass.getMethod(method.getName(), method.getParameterTypes(), method.isVarArgs()); if (interfaceMethod != null) { - // can be overridden by implement class + // Can be overridden by implement class annotations.addAll(interfaceMethod.getAnnotations()); } } @@ -84,6 +101,15 @@ default List getAnnotations(JavaMethod method) { return annotations; } + /** + * Handles the request mapping for a given method. + * @param projectBuilder Project documentation configuration builder + * @param controllerBaseUrl Base URL of the controller + * @param method The JavaMethod object representing the method to handle + * @param frameworkAnnotations Framework annotations related to the method + * @param requestMappingFunc Function to process request mappings + * @return The processed RequestMapping object + */ RequestMapping handle(ProjectDocConfigBuilder projectBuilder, String controllerBaseUrl, JavaMethod method, FrameworkAnnotations frameworkAnnotations, RequestMappingFunc requestMappingFunc); diff --git a/src/main/java/com/ly/doc/handler/JaxrsHeaderHandler.java b/src/main/java/com/ly/doc/handler/JaxrsHeaderHandler.java index bffbb307..a967db10 100644 --- a/src/main/java/com/ly/doc/handler/JaxrsHeaderHandler.java +++ b/src/main/java/com/ly/doc/handler/JaxrsHeaderHandler.java @@ -20,37 +20,40 @@ */ package com.ly.doc.handler; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; -import java.util.Objects; - +import com.ly.doc.builder.ProjectDocConfigBuilder; +import com.ly.doc.constants.DocTags; import com.ly.doc.constants.JAXRSAnnotations; import com.ly.doc.constants.JakartaJaxrsAnnotations; import com.ly.doc.model.ApiReqParam; +import com.ly.doc.utils.DocClassUtil; import com.ly.doc.utils.DocUtil; import com.power.common.util.StringUtil; -import com.ly.doc.builder.ProjectDocConfigBuilder; -import com.ly.doc.constants.DocTags; -import com.ly.doc.utils.DocClassUtil; import com.thoughtworks.qdox.model.JavaAnnotation; import com.thoughtworks.qdox.model.JavaMethod; import com.thoughtworks.qdox.model.JavaParameter; - import org.apache.commons.lang3.StringUtils; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.Objects; + /** - * Jaxrs Header Handler + * Jaxrs Header Handler This class is responsible for handling JAX-RS HTTP header + * parameter annotations. It parses the parameters and their annotations within a method + * to extract header information. * * @author Zxq */ public class JaxrsHeaderHandler { /** - * Handle JAX RS Header - * @param method method - * @param projectBuilder ProjectDocConfigBuilder - * @return list of ApiReqParam + * Handles JAX-RS headers for a given method. + * @param method The JavaMethod object representing the method whose headers are to be + * handled. + * @param projectBuilder The ProjectDocConfigBuilder object used to build project + * documentation configurations. + * @return A list of ApiReqParam objects representing the parsed header parameters. */ public List handle(JavaMethod method, ProjectDocConfigBuilder projectBuilder) { Map constantsMap = projectBuilder.getConstantsMap(); @@ -97,6 +100,13 @@ public List handle(JavaMethod method, ProjectDocConfigBuilder proje return apiReqHeaders; } + /** + * Generates a description string for a header parameter including its default value + * if provided. + * @param defaultValue The default value of the parameter. + * @param paramComments Any comments or descriptions associated with the parameter. + * @return A string containing the parameter description and default value. + */ private String getComments(String defaultValue, String paramComments) { if (Objects.nonNull(paramComments)) { StringBuilder desc = new StringBuilder(); diff --git a/src/main/java/com/ly/doc/handler/JaxrsPathHandler.java b/src/main/java/com/ly/doc/handler/JaxrsPathHandler.java index 8cfbfd26..204a5ea3 100644 --- a/src/main/java/com/ly/doc/handler/JaxrsPathHandler.java +++ b/src/main/java/com/ly/doc/handler/JaxrsPathHandler.java @@ -20,41 +20,56 @@ */ package com.ly.doc.handler; -import com.ly.doc.constants.*; -import com.power.common.util.StringUtil; -import com.power.common.util.UrlUtil; import com.ly.doc.builder.ProjectDocConfigBuilder; +import com.ly.doc.constants.*; import com.ly.doc.model.request.JaxrsPathMapping; import com.ly.doc.utils.DocUrlUtil; import com.ly.doc.utils.DocUtil; +import com.power.common.util.StringUtil; +import com.power.common.util.UrlUtil; import com.thoughtworks.qdox.model.JavaAnnotation; import com.thoughtworks.qdox.model.JavaMethod; import java.util.*; +import java.util.stream.Collectors; +import java.util.stream.Stream; import static com.ly.doc.constants.DocTags.DEPRECATED; import static com.ly.doc.constants.DocTags.IGNORE; /** - * Jaxrs Path Handler + * JAX-RS Path Handler This class is responsible for processing JAX-RS annotations on Java + * methods and generating corresponding path mapping information. * * @author Zxq */ public class JaxrsPathHandler { /** - * ANNOTATION_NAMES + * Set of annotation names related to JAX-RS path handling. */ - private static final Set ANNOTATION_NAMES = Collections - .unmodifiableSet(new HashSet<>(Arrays.asList(JakartaJaxrsAnnotations.JAXB_DELETE_FULLY, - JakartaJaxrsAnnotations.JAX_PUT_FULLY, JakartaJaxrsAnnotations.JAX_GET_FULLY, - JakartaJaxrsAnnotations.JAX_POST_FULLY, JakartaJaxrsAnnotations.JAX_PATCH_FULLY, - JakartaJaxrsAnnotations.JAX_HEAD_FULLY, JAXRSAnnotations.JAXB_DELETE_FULLY, - JAXRSAnnotations.JAX_PUT_FULLY, JAXRSAnnotations.JAX_GET_FULLY, JAXRSAnnotations.JAX_POST_FULLY, - JAXRSAnnotations.JAXB_PATCH_FULLY, JAXRSAnnotations.JAXB_HEAD_FULLY))); + private static final Set ANNOTATION_NAMES = Collections.unmodifiableSet(Stream + .of(JakartaJaxrsAnnotations.JAXB_DELETE_FULLY, JakartaJaxrsAnnotations.JAX_PUT_FULLY, + JakartaJaxrsAnnotations.JAX_GET_FULLY, JakartaJaxrsAnnotations.JAX_POST_FULLY, + JakartaJaxrsAnnotations.JAX_PATCH_FULLY, JakartaJaxrsAnnotations.JAX_HEAD_FULLY, + JAXRSAnnotations.JAXB_DELETE_FULLY, JAXRSAnnotations.JAX_PUT_FULLY, JAXRSAnnotations.JAX_GET_FULLY, + JAXRSAnnotations.JAX_POST_FULLY, JAXRSAnnotations.JAXB_PATCH_FULLY, JAXRSAnnotations.JAXB_HEAD_FULLY) + .collect(Collectors.toSet())); - Map constantsMap; + /** + * Map of constants used in the project. + */ + private Map constantsMap; + /** + * Handles JAX-RS annotations on a given method and generates path mapping + * information. + * @param projectBuilder The project documentation configuration builder + * @param baseUrl The base URL + * @param method The Java method object + * @param mediaType The media type + * @return A JaxrsPathMapping object containing the processed path information + */ public JaxrsPathMapping handle(ProjectDocConfigBuilder projectBuilder, String baseUrl, JavaMethod method, String mediaType) { @@ -105,6 +120,16 @@ public JaxrsPathMapping handle(ProjectDocConfigBuilder projectBuilder, String ba return null; } + /** + * Generates JAX-RS path mapping based on provided parameters. + * @param projectBuilder The project documentation configuration builder + * @param baseUrl The base URL + * @param method The Java method object + * @param shortUrl The short URL + * @param serverUrl The server URL + * @param contextPath The context path + * @return A JaxrsPathMapping object containing the processed path information + */ private JaxrsPathMapping getJaxbPathMapping(ProjectDocConfigBuilder projectBuilder, String baseUrl, JavaMethod method, String shortUrl, String serverUrl, String contextPath) { String url; diff --git a/src/main/java/com/ly/doc/handler/SolonRequestHeaderHandler.java b/src/main/java/com/ly/doc/handler/SolonRequestHeaderHandler.java index 61c3cf9c..3c87e86e 100644 --- a/src/main/java/com/ly/doc/handler/SolonRequestHeaderHandler.java +++ b/src/main/java/com/ly/doc/handler/SolonRequestHeaderHandler.java @@ -25,6 +25,8 @@ import com.ly.doc.model.annotation.HeaderAnnotation; /** + * Solon Request Header Handler + * * @author noear 2022/2/19 created */ public class SolonRequestHeaderHandler implements IHeaderHandler { diff --git a/src/main/java/com/ly/doc/handler/SolonRequestMappingHandler.java b/src/main/java/com/ly/doc/handler/SolonRequestMappingHandler.java index 29b1ec75..306f1b45 100644 --- a/src/main/java/com/ly/doc/handler/SolonRequestMappingHandler.java +++ b/src/main/java/com/ly/doc/handler/SolonRequestMappingHandler.java @@ -38,6 +38,8 @@ import static com.ly.doc.constants.DocTags.IGNORE; /** + * Solon RequestMapping Handler + * * @author noear 2022/2/19 created */ public class SolonRequestMappingHandler implements IRequestMappingHandler, IWebSocketRequestHandler { diff --git a/src/main/java/com/ly/doc/handler/SpringMVCRequestHeaderHandler.java b/src/main/java/com/ly/doc/handler/SpringMVCRequestHeaderHandler.java index c7470153..258a8e1a 100644 --- a/src/main/java/com/ly/doc/handler/SpringMVCRequestHeaderHandler.java +++ b/src/main/java/com/ly/doc/handler/SpringMVCRequestHeaderHandler.java @@ -25,6 +25,8 @@ import com.ly.doc.model.annotation.HeaderAnnotation; /** + * SpringMVC RequestHeaderHandler + * * @author yu 2019/12/22. */ public class SpringMVCRequestHeaderHandler implements IHeaderHandler { diff --git a/src/main/java/com/ly/doc/handler/SpringMVCRequestMappingHandler.java b/src/main/java/com/ly/doc/handler/SpringMVCRequestMappingHandler.java index 743a68c3..0daaf24f 100644 --- a/src/main/java/com/ly/doc/handler/SpringMVCRequestMappingHandler.java +++ b/src/main/java/com/ly/doc/handler/SpringMVCRequestMappingHandler.java @@ -42,17 +42,12 @@ import static com.ly.doc.constants.DocTags.IGNORE; /** + * Spring MVC RequestMapping Handler + * * @author yu 2019/12/22. */ public class SpringMVCRequestMappingHandler implements IRequestMappingHandler, IWebSocketRequestHandler { - /** - * handle spring request mapping - * @param projectBuilder projectBuilder - * @param controllerBaseUrl spring mvc controller base url - * @param method JavaMethod - * @return RequestMapping - */ @Override public RequestMapping handle(ProjectDocConfigBuilder projectBuilder, String controllerBaseUrl, JavaMethod method, FrameworkAnnotations frameworkAnnotations, RequestMappingFunc requestMappingFunc) { diff --git a/src/main/java/com/ly/doc/helper/BaseHelper.java b/src/main/java/com/ly/doc/helper/BaseHelper.java index 48d855fb..de3abb13 100644 --- a/src/main/java/com/ly/doc/helper/BaseHelper.java +++ b/src/main/java/com/ly/doc/helper/BaseHelper.java @@ -20,19 +20,28 @@ */ package com.ly.doc.helper; -import java.util.Map; - import com.ly.doc.constants.DocTags; import com.ly.doc.utils.DocUtil; import com.ly.doc.utils.JavaClassValidateUtil; import com.power.common.util.StringEscapeUtil; import com.power.common.util.StringUtil; +import java.util.Map; + /** + * Abstract Base helper + * * @author yu3.sun on 2022/10/14 */ public abstract class BaseHelper { + /** + * get field value from mock tag + * @param subTypeName subType name + * @param tagsMap tags map + * @param typeSimpleName type simple name + * @return field value + */ protected static String getFieldValueFromMockForJson(String subTypeName, Map tagsMap, String typeSimpleName) { String fieldValue = ""; @@ -48,6 +57,11 @@ protected static String getFieldValueFromMockForJson(String subTypeName, Map tagsMap) { String fieldValue = ""; if (tagsMap.containsKey(DocTags.MOCK) && StringUtil.isNotEmpty(tagsMap.get(DocTags.MOCK))) { diff --git a/src/main/java/com/ly/doc/helper/DocBuildHelper.java b/src/main/java/com/ly/doc/helper/DocBuildHelper.java index 09208046..5f56fffe 100644 --- a/src/main/java/com/ly/doc/helper/DocBuildHelper.java +++ b/src/main/java/com/ly/doc/helper/DocBuildHelper.java @@ -40,10 +40,16 @@ import java.util.stream.Collectors; /** + * + * Git Dependency Tree Helper + * * @author Fio */ public class DocBuildHelper { + /** + * JavaProjectBuilder + */ private JavaProjectBuilder projectBuilder; /** @@ -51,20 +57,33 @@ public class DocBuildHelper { */ private String codePath; + /** + * DependencyTree {@link DependencyTree} + */ private DependencyTree dependencyTree; + /** + * GitHelper {@link GitHelper} + */ private final GitHelper gitHelper = GitHelper.create(); /** * changed file list value set within {@link #getChangedFilesFromVCS(Predicate)} value * get within {@link #mergeDependencyTree(List)} */ - private Set fileDiffList = Collections.emptySet(); + private Set fileDiffList; + /** + * private constructor + */ private DocBuildHelper() { - } + /** + * Create a new {@link DocBuildHelper} object + * @param configBuilder {@link ProjectDocConfigBuilder} + * @return {@link DocBuildHelper} + */ public static DocBuildHelper create(ProjectDocConfigBuilder configBuilder) { ApiConfig apiConfig = configBuilder.getApiConfig(); @@ -97,6 +116,10 @@ public DependencyTree getDependencyTree() { return dependencyTree; } + /** + * Write the dependency-tree-file to baseDir + * @param dependencyTree dependency tree + */ private void writeDependencyTree(List dependencyTree) { if (gitHelper.notGitRepo()) { return; @@ -114,6 +137,12 @@ private void writeDependencyTree(List dependencyTree) { DependencyTree.write(this.dependencyTree); } + /** + * Merge dependency trees This method merges a new dependency tree into the existing + * one, removing any deleted or deprecated dependencies. + * @param newDependencyTree The new list of dependencies to be merged + * @return The merged list of dependencies after updates and removals + */ private List mergeDependencyTree(List newDependencyTree) { if (Objects.isNull(this.dependencyTree.getDependencyTree())) { return new ArrayList<>(); @@ -123,7 +152,7 @@ private List mergeDependencyTree(List newDependenc // remove the deleted or deprecated dependencies List deletedClazz = this.fileDiffList.stream() // newQualifiedName equals /dev/null means the class is deleted - .filter(item -> "/dev/null".equals(item.getNewQualifiedName())) + .filter(item -> DiffEntry.DEV_NULL.equals(item.getNewQualifiedName())) .map(FileDiff::getOldQualifiedName) .distinct() .collect(Collectors.toList()); @@ -215,6 +244,14 @@ public Set getChangedFilesFromVCS(Predicate isEntryPoint) { return fileDiffList; } + /** + * Gets the set of changed files. This method identifies changes in committed, + * uncommitted, and untracked files in the Git repository. + * @param diff A list of DiffEntry objects representing changes in the Git tree. + * @param uncommitted A set of strings representing paths to uncommitted changes. + * @param untracked A set of strings representing paths to untracked files. + * @return A Set of FileDiff objects representing all the changed files. + */ private Set getChangedFiles(List diff, Set uncommitted, Set untracked) { diff.removeIf(item -> !isSupportedSourceCodeType(item.getNewPath())); uncommitted.removeIf(item -> !isSupportedSourceCodeType(item)); @@ -258,7 +295,9 @@ private Set getChangedFiles(List diff, Set uncommit } /** - * convert the relative path from git to package + * Convert the relative path to qualified name. + * @param relativePath the relative path + * @return the qualified name */ private String toQualifiedName(String relativePath) { // /dev/null is git default path when a file is added or deleted @@ -284,11 +323,21 @@ private String toQualifiedName(String relativePath) { return filePath.replace(File.separator, "."); } + /** + * Check whether the file is supported source code type. + * @param path the path + * @return the boolean + */ private boolean isSupportedSourceCodeType(String path) { // maybe there's a better way... return path.endsWith(".java") || path.endsWith(".kt") || path.endsWith(".groovy") || path.endsWith(".scala"); } + /** + * Populate the related clazz and mark the entry point. + * @param diffList the diff list + * @param isEntryPoint the entry point predicate + */ private void populateRelatedClazzAndMarkEntryPoint(Set diffList, Predicate isEntryPoint) { List oldDependencyTree = this.dependencyTree.getDependencyTree(); @@ -348,11 +397,23 @@ private void populateRelatedClazzAndMarkEntryPoint(Set diffList, Predi }); } + /** + * Rebuilds the dependency tree. + * @param the type parameter representing the kind of document, which must extend + * the IDoc interface + * @param apiList a list of documents that implement the IDoc interface + */ public void rebuildDependencyTree(List apiList) { List dependencyTree = buildDependencyTree(apiList); writeDependencyTree(dependencyTree); } + /** + * Builds a dependency tree. + * @param the generic type of the document, must be a subclass of IDoc + * @param apiList a list containing API documents + * @return a list of ApiDependency objects representing the built dependency tree + */ private List buildDependencyTree(List apiList) { if (CollectionUtil.isEmpty(apiList)) { return Collections.emptyList(); @@ -389,6 +450,10 @@ private List buildDependencyTree(List apiList return dependencyTree; } + /** + * Determines if the current project is not a Git repository. + * @return true if the current project is not a Git repository, false otherwise. + */ public boolean notGitRepo() { return gitHelper.notGitRepo(); } diff --git a/src/main/java/com/ly/doc/helper/FormDataBuildHelper.java b/src/main/java/com/ly/doc/helper/FormDataBuildHelper.java index c5a866ec..44d5bda6 100644 --- a/src/main/java/com/ly/doc/helper/FormDataBuildHelper.java +++ b/src/main/java/com/ly/doc/helper/FormDataBuildHelper.java @@ -39,6 +39,8 @@ import java.util.*; /** + * FormData Builder {@link FormData } + * * @author yu 2019/12/25. */ public class FormDataBuildHelper extends BaseHelper { diff --git a/src/main/java/com/ly/doc/helper/GitHelper.java b/src/main/java/com/ly/doc/helper/GitHelper.java index 224bbb14..ad4f608c 100644 --- a/src/main/java/com/ly/doc/helper/GitHelper.java +++ b/src/main/java/com/ly/doc/helper/GitHelper.java @@ -44,17 +44,32 @@ */ public class GitHelper { + /** + * Repository + */ private Repository repository; + /** + * Private constructor + */ private GitHelper() { } + /** + * Create a new instance + * @return GitHelper + */ public static GitHelper create() { GitHelper helper = new GitHelper(); helper.repository = helper.findRepo(); return helper; } + /** + * Get diff between current commit and the commit with commitId + * @param commitId commitId + * @return {@code List} + */ public List getDiff(String commitId) { if (StringUtil.isEmpty(commitId) || notGitRepo()) { return Collections.emptyList(); @@ -83,6 +98,10 @@ public List getDiff(String commitId) { } } + /** + * Get uncommitted changes + * @return {@code Set } + */ public Set getUncommitted() { if (notGitRepo()) { return Collections.emptySet(); @@ -96,6 +115,10 @@ public Set getUncommitted() { } } + /** + * Get untracked files + * @return {@code Set } + */ public Set getUntracked() { if (notGitRepo()) { return Collections.emptySet(); @@ -109,6 +132,10 @@ public Set getUntracked() { } } + /** + * Get latest commit id + * @return latest commit id + */ public String getLatestCommitId() { if (notGitRepo()) { return ""; @@ -129,6 +156,7 @@ public String getLatestCommitId() { /** * Check git repository, if not exist or io exception, return null + * @return Repository */ private Repository findRepo() { try { @@ -144,14 +172,26 @@ private Repository findRepo() { } } + /** + * Check if not git repository + * @return boolean + */ public boolean notGitRepo() { return repository == null; } + /** + * Check if git repository + * @return boolean + */ public boolean isGitRepo() { return !notGitRepo(); } + /** + * Get work directory + * @return work directory + */ public String getWorkDir() { return repository.getWorkTree().getAbsolutePath(); } diff --git a/src/main/java/com/ly/doc/helper/JavaProjectBuilderHelper.java b/src/main/java/com/ly/doc/helper/JavaProjectBuilderHelper.java index 74600282..8f866355 100644 --- a/src/main/java/com/ly/doc/helper/JavaProjectBuilderHelper.java +++ b/src/main/java/com/ly/doc/helper/JavaProjectBuilderHelper.java @@ -30,10 +30,26 @@ */ public class JavaProjectBuilderHelper { + /** + * private constructor + */ + private JavaProjectBuilderHelper() { + throw new IllegalStateException("Utility class"); + } + + /** + * create a new {@link JavaProjectBuilder} object + * @return a new {@link JavaProjectBuilder} object + */ public static JavaProjectBuilder create() { return new JavaProjectBuilder(); } + /** + * create a new {@link JavaProjectBuilder} object + * @param classLibraryBuilder the {@link ClassLibraryBuilder} object + * @return a new {@link JavaProjectBuilder} object + */ public static JavaProjectBuilder create(ClassLibraryBuilder classLibraryBuilder) { return new JavaProjectBuilder(classLibraryBuilder); } diff --git a/src/main/java/com/ly/doc/helper/JsonBuildHelper.java b/src/main/java/com/ly/doc/helper/JsonBuildHelper.java index 349f914e..e7c59702 100644 --- a/src/main/java/com/ly/doc/helper/JsonBuildHelper.java +++ b/src/main/java/com/ly/doc/helper/JsonBuildHelper.java @@ -34,6 +34,8 @@ import static com.ly.doc.constants.DocTags.IGNORE_RESPONSE_BODY_ADVICE; /** + * Json Builder + * * @author yu 2019/12/21. */ public class JsonBuildHelper extends BaseHelper { diff --git a/src/main/java/com/ly/doc/helper/ParamsBuildHelper.java b/src/main/java/com/ly/doc/helper/ParamsBuildHelper.java index 5213f407..309e23bd 100644 --- a/src/main/java/com/ly/doc/helper/ParamsBuildHelper.java +++ b/src/main/java/com/ly/doc/helper/ParamsBuildHelper.java @@ -42,6 +42,8 @@ import java.util.stream.Collectors; /** + * ApiParam Builder {@link ApiParam } + * * @author yu 2019/12/21. */ public class ParamsBuildHelper extends BaseHelper { diff --git a/src/main/java/com/ly/doc/model/ApiConstant.java b/src/main/java/com/ly/doc/model/ApiConstant.java index d4dd1498..3b697908 100644 --- a/src/main/java/com/ly/doc/model/ApiConstant.java +++ b/src/main/java/com/ly/doc/model/ApiConstant.java @@ -28,7 +28,7 @@ public class ApiConstant { /** * Constants class */ - private Class constantsClass; + private Class constantsClass; /** * Constants class name @@ -44,11 +44,11 @@ public static ApiConstant builder() { return new ApiConstant(); } - public Class getConstantsClass() { + public Class getConstantsClass() { return constantsClass; } - public ApiConstant setConstantsClass(Class constantsClass) { + public ApiConstant setConstantsClass(Class constantsClass) { this.constantsClass = constantsClass; return this; } @@ -73,12 +73,8 @@ public ApiConstant setDescription(String description) { @Override public String toString() { - final StringBuilder sb = new StringBuilder("{"); - sb.append("\"constantsClass\":").append(constantsClass); - sb.append(",\"constantsClassName\":\"").append(constantsClassName).append('\"'); - sb.append(",\"description\":\"").append(description).append('\"'); - sb.append('}'); - return sb.toString(); + return "{" + "\"constantsClass\":" + constantsClass + ",\"constantsClassName\":\"" + constantsClassName + '\"' + + ",\"description\":\"" + description + '\"' + '}'; } } diff --git a/src/main/java/com/ly/doc/model/ApiSchema.java b/src/main/java/com/ly/doc/model/ApiSchema.java index 2d38e62f..18d48a33 100644 --- a/src/main/java/com/ly/doc/model/ApiSchema.java +++ b/src/main/java/com/ly/doc/model/ApiSchema.java @@ -21,14 +21,19 @@ package com.ly.doc.model; +import java.io.Serializable; import java.util.ArrayList; import java.util.List; /** + * Api Schema + * * @author yu.sun on 2024/6/9 * @since 3.0.5 */ -public class ApiSchema { +public class ApiSchema implements Serializable { + + private static final long serialVersionUID = -8712793142951321786L; List apiDatas; diff --git a/src/main/java/com/ly/doc/model/BodyAdvice.java b/src/main/java/com/ly/doc/model/BodyAdvice.java index 6b941819..b079ce92 100644 --- a/src/main/java/com/ly/doc/model/BodyAdvice.java +++ b/src/main/java/com/ly/doc/model/BodyAdvice.java @@ -28,7 +28,7 @@ public class BodyAdvice { private String className; - private Class wrapperClass; + private Class wrapperClass; private String dataField; @@ -54,22 +54,18 @@ public BodyAdvice setDataField(String dataField) { return this; } - public Class getWrapperClass() { + public Class getWrapperClass() { return wrapperClass; } - public BodyAdvice setWrapperClass(Class wrapperClass) { + public BodyAdvice setWrapperClass(Class wrapperClass) { this.wrapperClass = wrapperClass; return this; } @Override public String toString() { - final StringBuilder sb = new StringBuilder("{"); - sb.append("\"className\":\"").append(className).append('\"'); - sb.append(",\"dataField\":\"").append(dataField).append('\"'); - sb.append('}'); - return sb.toString(); + return "{" + "\"className\":\"" + className + '\"' + ",\"dataField\":\"" + dataField + '\"' + '}'; } } diff --git a/src/main/java/com/ly/doc/model/FormData.java b/src/main/java/com/ly/doc/model/FormData.java index c07dc9cb..358adc74 100644 --- a/src/main/java/com/ly/doc/model/FormData.java +++ b/src/main/java/com/ly/doc/model/FormData.java @@ -69,9 +69,8 @@ public boolean isHasItems() { return hasItems; } - public FormData setHasItems(boolean hasItems) { + public void setHasItems(boolean hasItems) { this.hasItems = hasItems; - return this; } public String getKey() { diff --git a/src/main/java/com/ly/doc/template/GRpcDocBuildTemplate.java b/src/main/java/com/ly/doc/template/GRpcDocBuildTemplate.java index af486b14..994d1e07 100644 --- a/src/main/java/com/ly/doc/template/GRpcDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/GRpcDocBuildTemplate.java @@ -344,7 +344,7 @@ private void executeCommand(List command, ProtoInfo protoInfo) { try { Process process = processBuilder.start(); - StreamGobbler outputGobbler = new StreamGobbler(process.getInputStream(), message -> log.warning(message)); + StreamGobbler outputGobbler = new StreamGobbler(process.getInputStream(), log::warning); Thread outputThread = new Thread(outputGobbler); outputThread.start(); @@ -423,7 +423,7 @@ private List processMessage(Message message, int level) { .setDesc(fieldDesc) .setRequired(!"optional".equals(field.getLabel()) || "required".equals(field.getLabel()) || "".equals(field.getLabel())) - .setVersion("-") + .setVersion(DocGlobalConstants.DEFAULT_VERSION) .setValue(field.getDefaultValue()) .setClassName(field.getFullType()) .setId(level) diff --git a/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java b/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java index ef1b9b45..3f2d2d1c 100644 --- a/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/IBaseDocBuildTemplate.java @@ -35,10 +35,17 @@ import static com.ly.doc.constants.DocGlobalConstants.NO_COMMENTS_FOUND; /** + * Base Doc Build Template + * * @author yu3.sun on 2022/10/2 */ public interface IBaseDocBuildTemplate { + /** + * Comment Resolve + * @param comment comment + * @return String + */ default String paramCommentResolve(String comment) { if (StringUtil.isEmpty(comment)) { comment = NO_COMMENTS_FOUND; @@ -130,6 +137,15 @@ default void convertParamsDataToTree(ApiMethodDoc apiMethodDoc) { apiMethodDoc.setRequestParams(ApiParamTreeUtil.apiParamToTree(apiMethodDoc.getRequestParams())); } + /** + * Retrieves and processes the list of parameters for a given Java method, applying + * various transformations and ignoring specified parameters. + * @param builder The project documentation configuration builder. + * @param docJavaMethod The documented Java method. + * @param frameworkAnnotations The framework annotations used to identify specific + * annotations. + * @return A list of processed {@link DocJavaParameter} objects. + */ default List getJavaParameterList(ProjectDocConfigBuilder builder, final DocJavaMethod docJavaMethod, FrameworkAnnotations frameworkAnnotations) { JavaMethod javaMethod = docJavaMethod.getJavaMethod(); @@ -202,6 +218,15 @@ default List getJavaParameterList(ProjectDocConfigBuilder buil return apiJavaParameterList; } + /** + * Retrieves the rewritten class name based on the provided map, full type name, and + * comment class. + * @param replacementMap The map containing replacements for class names. + * @param fullTypeName The fully qualified type name. + * @param commentClass The comment associated with the class, if any. + * @return The rewritten class name or the original class name if no valid rewrite is + * found. + */ default String getRewriteClassName(Map replacementMap, String fullTypeName, String commentClass) { String rewriteClassName; if (Objects.nonNull(commentClass) && !DocGlobalConstants.NO_COMMENTS_FOUND.equals(commentClass)) { @@ -217,6 +242,12 @@ default String getRewriteClassName(Map replacementMap, String fu return replacementMap.get(fullTypeName); } + /** + * Retrieves a set of parameter names to be ignored based on the `@ignoreParams` tag + * in the method's documentation. + * @param method The Java method to inspect for the ignore parameters tag. + * @return A set of parameter names that should be ignored. + */ default Set ignoreParamsSets(JavaMethod method) { Set ignoreSets = new HashSet<>(); DocletTag ignoreParam = method.getTagByName(DocTags.IGNORE_PARAMS); @@ -227,10 +258,17 @@ default Set ignoreParamsSets(JavaMethod method) { return ignoreSets; } + /** + * Retrieves the simplified return type of a Java method, handling generic types and + * array notations. + * @param javaMethod The Java method whose return type needs to be processed. + * @param actualTypesMap A map containing actual type mappings. + * @return The simplified return type as a string. + */ default String getMethodReturnType(JavaMethod javaMethod, Map actualTypesMap) { JavaType returnType = javaMethod.getReturnType(); - String simpleReturn = replaceTypeName(returnType.getCanonicalName(), actualTypesMap, Boolean.TRUE); - String returnClass = replaceTypeName(returnType.getGenericCanonicalName(), actualTypesMap, Boolean.TRUE); + String simpleReturn = this.replaceTypeName(returnType.getCanonicalName(), actualTypesMap, Boolean.TRUE); + String returnClass = this.replaceTypeName(returnType.getGenericCanonicalName(), actualTypesMap, Boolean.TRUE); returnClass = returnClass.replace(simpleReturn, JavaClassUtil.getClassSimpleName(simpleReturn)); String[] arrays = DocClassUtil.getSimpleGicName(returnClass); for (String str : arrays) { @@ -252,6 +290,13 @@ default String getMethodReturnType(JavaMethod javaMethod, Map return returnClass; } + /** + * Replaces type names in the given string based on the provided map of actual types. + * @param type The type name to be replaced. + * @param actualTypesMap A map containing the actual types to be used for replacement. + * @param simple A flag indicating whether to use simple names for replacement. + * @return The type name after replacement. + */ default String replaceTypeName(String type, Map actualTypesMap, boolean simple) { if (Objects.isNull(actualTypesMap)) { return type; @@ -269,6 +314,13 @@ default String replaceTypeName(String type, Map actualTypesMap return type; } + /** + * Determines whether the return object should be ignored based on its type name and a + * list of ignored parameters. + * @param typeName The name of the type to check. + * @param ignoreParams A list of parameter names that should be ignored. + * @return true if the return object should be ignored; false otherwise. + */ boolean ignoreReturnObject(String typeName, List ignoreParams); } diff --git a/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java b/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java index 9da1e7c0..fc64963e 100644 --- a/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java +++ b/src/main/java/com/ly/doc/template/IDocBuildBaseTemplate.java @@ -199,7 +199,7 @@ default boolean isEntryPoint(JavaProjectBuilder javaProjectBuilder, String javaC return false; } - return isEntryPoint(javaClass, registeredAnnotations()); + return this.isEntryPoint(javaClass, this.registeredAnnotations()); } /** @@ -229,7 +229,7 @@ default boolean skipClass(ApiConfig apiConfig, JavaClass javaClass, FrameworkAnn } // from tag DocletTag ignoreTag = javaClass.getTagByName(DocTags.IGNORE); - return !isEntryPoint(javaClass, frameworkAnnotations) || Objects.nonNull(ignoreTag); + return !this.isEntryPoint(javaClass, frameworkAnnotations) || Objects.nonNull(ignoreTag); } /** diff --git a/src/main/java/com/ly/doc/template/IDocBuildTemplate.java b/src/main/java/com/ly/doc/template/IDocBuildTemplate.java index 99f4f266..fda64fc9 100644 --- a/src/main/java/com/ly/doc/template/IDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/IDocBuildTemplate.java @@ -32,6 +32,9 @@ import java.util.Objects; /** + * Defines the contract for a document build template that processes API schemas. + * + * @param The type of document being built. * @author yu 2019/12/21. */ public interface IDocBuildTemplate extends IDocBuildBaseTemplate { diff --git a/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java b/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java index 7a389e67..7122373a 100644 --- a/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java +++ b/src/main/java/com/ly/doc/template/IJavadocDocTemplate.java @@ -126,7 +126,7 @@ default String methodDefinition(JavaMethod method, Map actualT List params = new ArrayList<>(); List parameters = method.getParameters(); for (JavaParameter parameter : parameters) { - String typeName = replaceTypeName(parameter.getType().getGenericValue(), actualTypesMap, Boolean.TRUE); + String typeName = this.replaceTypeName(parameter.getType().getGenericValue(), actualTypesMap, Boolean.TRUE); params.add(typeName + " " + parameter.getName()); } methodBuilder.append(method.getName()).append("(").append(String.join(", ", params)).append(")"); @@ -210,11 +210,11 @@ default List requestParams(final JavaMethod javaMethod, ProjectDocConf for (JavaParameter parameter : parameterList) { boolean required = false; String paramName = parameter.getName(); - String typeName = replaceTypeName(parameter.getType().getGenericCanonicalName(), actualTypesMap, + String typeName = this.replaceTypeName(parameter.getType().getGenericCanonicalName(), actualTypesMap, Boolean.FALSE); - String simpleName = replaceTypeName(parameter.getType().getValue(), actualTypesMap, Boolean.FALSE) + String simpleName = this.replaceTypeName(parameter.getType().getValue(), actualTypesMap, Boolean.FALSE) .toLowerCase(); - String fullTypeName = replaceTypeName(parameter.getType().getFullyQualifiedName(), actualTypesMap, + String fullTypeName = this.replaceTypeName(parameter.getType().getFullyQualifiedName(), actualTypesMap, Boolean.FALSE); String paramPre = paramName + "."; if (!paramTagMap.containsKey(paramName) && JavaClassValidateUtil.isPrimitive(fullTypeName) && isStrict) { diff --git a/src/main/java/com/ly/doc/template/IRestDocTemplate.java b/src/main/java/com/ly/doc/template/IRestDocTemplate.java index babe17a8..fc6c2797 100644 --- a/src/main/java/com/ly/doc/template/IRestDocTemplate.java +++ b/src/main/java/com/ly/doc/template/IRestDocTemplate.java @@ -569,7 +569,7 @@ default List buildExceptionStatus(ProjectDocConfigBuilder pr for (JavaClass cls : javaClasses) { // from tag DocletTag ignoreTag = cls.getTagByName(DocTags.IGNORE); - if (!isExceptionAdviceEntryPoint(cls, frameworkAnnotations) || Objects.nonNull(ignoreTag)) { + if (!this.isExceptionAdviceEntryPoint(cls, frameworkAnnotations) || Objects.nonNull(ignoreTag)) { continue; } boolean paramsDataToTree = projectBuilder.getApiConfig().isParamsDataToTree(); diff --git a/src/main/java/com/ly/doc/template/JAXRSDocBuildTemplate.java b/src/main/java/com/ly/doc/template/JAXRSDocBuildTemplate.java index 6b9a8e27..42212228 100644 --- a/src/main/java/com/ly/doc/template/JAXRSDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/JAXRSDocBuildTemplate.java @@ -54,6 +54,9 @@ public class JAXRSDocBuildTemplate implements IDocBuildTemplate, IWebSocketDocBuildTemplate, IRestDocTemplate, IWebSocketTemplate { + /** + * logger + */ private static final Logger log = Logger.getLogger(JAXRSDocBuildTemplate.class.getName()); /** @@ -84,15 +87,15 @@ public List buildEntryPointMethod(JavaClass cls, ApiConfig apiConf ProjectDocConfigBuilder projectBuilder, FrameworkAnnotations frameworkAnnotations, List configApiReqParams, IRequestMappingHandler baseMappingHandler, IHeaderHandler headerHandler) { - return buildControllerMethod(cls, apiConfig, projectBuilder, frameworkAnnotations); + return this.buildControllerMethod(cls, apiConfig, projectBuilder, frameworkAnnotations); } @Override public List renderWebSocketApi(ProjectDocConfigBuilder projectBuilder, Collection candidateClasses) { - FrameworkAnnotations frameworkAnnotations = registeredAnnotations(); - return processWebSocketData(projectBuilder, frameworkAnnotations, DefaultWebSocketRequestHandler.getInstance(), - candidateClasses); + FrameworkAnnotations frameworkAnnotations = this.registeredAnnotations(); + return this.processWebSocketData(projectBuilder, frameworkAnnotations, + DefaultWebSocketRequestHandler.getInstance(), candidateClasses); } /** diff --git a/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java b/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java index 9ebaa8d2..5b39a6c1 100644 --- a/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/JavadocDocBuildTemplate.java @@ -146,6 +146,17 @@ public FrameworkAnnotations registeredAnnotations() { return null; } + /** + * Handles the generation of Java API documentation. This method is responsible for + * creating an API documentation object based on the provided Java class information + * and populating its properties. + * @param cls The Java class from which to extract documentation information. + * @param apiDocList A list where the generated API documentation objects will be + * added. + * @param apiMethodDocs A list containing documentation for methods within the class. + * @param order The order in which the API documentation should be listed. + * @param builder A builder used to retrieve class information and configurations. + */ private void handleJavaApiDoc(JavaClass cls, List apiDocList, List apiMethodDocs, int order, ProjectDocConfigBuilder builder) { String className = cls.getCanonicalName(); diff --git a/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java b/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java index 10c4c2cf..f70bae29 100644 --- a/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/RpcDocBuildTemplate.java @@ -160,6 +160,18 @@ public FrameworkAnnotations registeredAnnotations() { return null; } + /** + * Handles the generation of Java API documentation. This method is responsible for + * processing a Java class to generate API documentation details, including setting up + * the API documentation list and method details. + * @param cls The JavaClass object representing the class being documented. + * @param apiDocList The list to store generated RpcApiDoc objects. + * @param apiMethodDocs The list containing documentation for methods within the + * class. + * @param order The order or priority of the API documentation. + * @param builder The ProjectDocConfigBuilder used to configure and retrieve class + * information. + */ private void handleJavaApiDoc(JavaClass cls, List apiDocList, List apiMethodDocs, int order, ProjectDocConfigBuilder builder) { String className = cls.getCanonicalName(); diff --git a/src/main/java/com/ly/doc/template/SolonDocBuildTemplate.java b/src/main/java/com/ly/doc/template/SolonDocBuildTemplate.java index 3c669d03..9f91992c 100644 --- a/src/main/java/com/ly/doc/template/SolonDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/SolonDocBuildTemplate.java @@ -57,7 +57,7 @@ public ApiSchema renderApi(ProjectDocConfigBuilder projectBuilder, Colle .filter(Objects::nonNull) .flatMap(Collection::stream) .collect(Collectors.toList()); - FrameworkAnnotations frameworkAnnotations = registeredAnnotations(); + FrameworkAnnotations frameworkAnnotations = this.registeredAnnotations(); return this.processApiData(projectBuilder, frameworkAnnotations, configApiReqParams, new SolonRequestMappingHandler(), new SolonRequestHeaderHandler(), candidateClasses); } diff --git a/src/main/java/com/ly/doc/template/SpringBootDocBuildTemplate.java b/src/main/java/com/ly/doc/template/SpringBootDocBuildTemplate.java index 41fd693a..2b994ca7 100644 --- a/src/main/java/com/ly/doc/template/SpringBootDocBuildTemplate.java +++ b/src/main/java/com/ly/doc/template/SpringBootDocBuildTemplate.java @@ -59,7 +59,7 @@ public ApiSchema renderApi(ProjectDocConfigBuilder projectBuilder, Colle .filter(Objects::nonNull) .flatMap(Collection::stream) .collect(Collectors.toList()); - FrameworkAnnotations frameworkAnnotations = registeredAnnotations(); + FrameworkAnnotations frameworkAnnotations = this.registeredAnnotations(); return this.processApiData(projectBuilder, frameworkAnnotations, configApiReqParams, new SpringMVCRequestMappingHandler(), new SpringMVCRequestHeaderHandler(), candidateClasses); } @@ -67,7 +67,7 @@ public ApiSchema renderApi(ProjectDocConfigBuilder projectBuilder, Colle @Override public List renderWebSocketApi(ProjectDocConfigBuilder projectBuilder, Collection candidateClasses) { - FrameworkAnnotations frameworkAnnotations = registeredAnnotations(); + FrameworkAnnotations frameworkAnnotations = this.registeredAnnotations(); return this.processWebSocketData(projectBuilder, frameworkAnnotations, new SpringMVCRequestMappingHandler(), candidateClasses); } diff --git a/src/main/java/com/ly/doc/utils/ApiParamTreeUtil.java b/src/main/java/com/ly/doc/utils/ApiParamTreeUtil.java index eddc7603..38b578ec 100644 --- a/src/main/java/com/ly/doc/utils/ApiParamTreeUtil.java +++ b/src/main/java/com/ly/doc/utils/ApiParamTreeUtil.java @@ -34,10 +34,24 @@ import java.util.stream.Collectors; /** + * ApiParam Tree Util {@link ApiParam} + * * @author yu 2020/8/8. */ public class ApiParamTreeUtil { + /** + * private constructor + */ + private ApiParamTreeUtil() { + throw new IllegalStateException("Utility class"); + } + + /** + * Converts a list of ApiParam objects into a tree structure. + * @param apiParamList The list of ApiParam objects to be converted. + * @return A list of ApiParam objects representing the tree structure. + */ public static List apiParamToTree(List apiParamList) { if (CollectionUtil.isEmpty(apiParamList)) { return new ArrayList<>(0); diff --git a/src/main/java/com/ly/doc/utils/BeetlTemplateUtil.java b/src/main/java/com/ly/doc/utils/BeetlTemplateUtil.java index 70c98c4f..dc544b18 100644 --- a/src/main/java/com/ly/doc/utils/BeetlTemplateUtil.java +++ b/src/main/java/com/ly/doc/utils/BeetlTemplateUtil.java @@ -20,19 +20,18 @@ */ package com.ly.doc.utils; -import java.io.File; -import java.io.IOException; -import java.util.HashMap; -import java.util.Map; -import java.util.Objects; - import com.power.common.util.FileUtil; - import org.beetl.core.Configuration; import org.beetl.core.GroupTemplate; import org.beetl.core.Template; import org.beetl.core.resource.ClasspathResourceLoader; +import java.io.File; +import java.io.IOException; +import java.util.HashMap; +import java.util.Map; +import java.util.Objects; + /** * Beetl template handle util * @@ -40,6 +39,13 @@ */ public class BeetlTemplateUtil { + /** + * private constructor + */ + private BeetlTemplateUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Get Beetl template by file name * @param templateName template name diff --git a/src/main/java/com/ly/doc/utils/CurlUtil.java b/src/main/java/com/ly/doc/utils/CurlUtil.java index e5e5e507..792bc754 100644 --- a/src/main/java/com/ly/doc/utils/CurlUtil.java +++ b/src/main/java/com/ly/doc/utils/CurlUtil.java @@ -37,6 +37,18 @@ */ public class CurlUtil { + /** + * private constructor + */ + private CurlUtil() { + throw new IllegalStateException("Utility class"); + } + + /** + * convert curl request to curl string + * @param request CurlRequest + * @return String + */ public static String toCurl(CurlRequest request) { if (Objects.isNull(request)) { return ""; diff --git a/src/main/java/com/ly/doc/utils/DocClassUtil.java b/src/main/java/com/ly/doc/utils/DocClassUtil.java index f873de38..c329a03d 100644 --- a/src/main/java/com/ly/doc/utils/DocClassUtil.java +++ b/src/main/java/com/ly/doc/utils/DocClassUtil.java @@ -36,6 +36,13 @@ */ public class DocClassUtil { + /** + * private constructor + */ + private DocClassUtil() { + throw new IllegalStateException("Utility class"); + } + /** * get class names by generic class name * @param typeName generic class name @@ -395,14 +402,17 @@ public static ApiReturn processReturnType(String fullyName) { * @return String */ public static String rewriteRequestParam(String typeName) { - switch (typeName) { - case "org.springframework.data.domain.Pageable": - return "com.ly.doc.model.framework.PageableAsQueryParam"; - default: - return typeName; + if (typeName.equals("org.springframework.data.domain.Pageable")) { + return "com.ly.doc.model.framework.PageableAsQueryParam"; } + return typeName; } + /** + * Check if the given string is a valid class name. + * @param className The string to check. + * @return True if the string is a valid class name, false otherwise. + */ private static boolean isClassName(String className) { className = className.replaceAll("[^<>]", ""); Stack stack = new Stack<>(); @@ -438,6 +448,12 @@ public static List getAnnotations(JavaClass cls) { return classAnnotations; } + /** + * Create an instance of the given class using its default constructor. + * @param The type of the class to create an instance of. + * @param classWithNoArgsConstructor The class to create an instance of. + * @return An instance of the given class. + */ public static T newInstance(Class classWithNoArgsConstructor) { try { return classWithNoArgsConstructor.getConstructor().newInstance(); diff --git a/src/main/java/com/ly/doc/utils/DocPathUtil.java b/src/main/java/com/ly/doc/utils/DocPathUtil.java index 39e3b5a1..25a054a6 100644 --- a/src/main/java/com/ly/doc/utils/DocPathUtil.java +++ b/src/main/java/com/ly/doc/utils/DocPathUtil.java @@ -35,6 +35,13 @@ */ public class DocPathUtil { + /** + * private constructor + */ + private DocPathUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Get the java class name * @param parentDir parent dir diff --git a/src/main/java/com/ly/doc/utils/DocUrlUtil.java b/src/main/java/com/ly/doc/utils/DocUrlUtil.java index 34f08e03..bc99d3e1 100644 --- a/src/main/java/com/ly/doc/utils/DocUrlUtil.java +++ b/src/main/java/com/ly/doc/utils/DocUrlUtil.java @@ -20,19 +20,40 @@ */ package com.ly.doc.utils; -import java.util.List; -import java.util.Map; -import java.util.Optional; - import com.ly.doc.constants.DocGlobalConstants; import com.power.common.util.StringUtil; import com.power.common.util.UrlUtil; +import java.util.List; +import java.util.Map; +import java.util.Optional; + /** + * Utility class for handling URL operations related to documentation. + *

+ * This class provides methods to construct and format URLs. It is not intended to be + * instantiated. + * * @author yu 2019/12/22. */ public class DocUrlUtil { + /** + * private constructor + */ + private DocUrlUtil() { + throw new IllegalStateException("Utility class"); + } + + /** + * Constructs a list of formatted URLs based on the provided base server, base URL, + * and a list of URLs. + * @param baseServer The base server URL. + * @param baseUrl The base URL segment. + * @param urls A list of URL segments to append. + * @return A concatenated string of simplified URLs separated by a predefined + * separator. + */ public static String getMvcUrls(String baseServer, String baseUrl, List urls) { StringBuilder sb = new StringBuilder(); List baseUrls = DocUtil.split(baseUrl); @@ -64,11 +85,27 @@ public static String getMvcUrls(String baseServer, String baseUrl, List return sb.toString(); } + /** + * Convenience method to construct a formatted URL based on the provided base server, + * base URL, and a short URL. + * @param baseServer The base server URL. + * @param baseUrl The base URL segment. + * @param shortUrl A short URL to split and process. + * @return A formatted URL. + */ public static String getMvcUrls(String baseServer, String baseUrl, String shortUrl) { List urls = DocUtil.split(shortUrl); return getMvcUrls(baseServer, baseUrl, urls); } + /** + * Formats a request URL with path parameters and query parameters. + * @param pathParamsMap A map of path parameters. + * @param queryParamsMap A map of query parameters. + * @param serverUrl The server URL. + * @param path The path to be formatted. + * @return A fully constructed and simplified request URL. + */ public static String formatRequestUrl(Map pathParamsMap, Map queryParamsMap, String serverUrl, String path) { path = DocUtil.formatAndRemove(path, pathParamsMap); diff --git a/src/main/java/com/ly/doc/utils/DocUtil.java b/src/main/java/com/ly/doc/utils/DocUtil.java index 65dba519..58216a13 100644 --- a/src/main/java/com/ly/doc/utils/DocUtil.java +++ b/src/main/java/com/ly/doc/utils/DocUtil.java @@ -40,6 +40,7 @@ import java.time.*; import java.time.format.DateTimeFormatter; import java.util.*; +import java.util.logging.Logger; import java.util.regex.Pattern; import java.util.stream.Collectors; @@ -50,11 +51,32 @@ */ public class DocUtil { + /** + * private constructor + */ + private DocUtil() { + throw new IllegalStateException("Utility class"); + } + + /** + * logger + */ + private static final Logger logger = Logger.getLogger(DocUtil.class.getName()); + + /** + * Faker + */ private static final Faker FAKER = new Faker(new Locale("en-US")); + /** + * En-Faker + */ private static final Faker EN_FAKER = new Faker(new Locale("en-US")); - private static final Map FIELD_VALUE = new LinkedHashMap<>(); + /** + * Field value map + */ + private static final Map FIELD_VALUE = new LinkedHashMap<>(64); static { FIELD_VALUE.put("uuid-string", UUID.randomUUID().toString()); @@ -225,13 +247,8 @@ public static String jsonValueByType(String typeName) { } String randomMock = System.getProperty(DocGlobalConstants.RANDOM_MOCK); boolean randomMockFlag = Boolean.parseBoolean(randomMock); - String value = ""; - if (randomMockFlag) { - value = RandomUtil.randomValueByType(type); - } - else { - value = RandomUtil.generateDefaultValueByType(type); - } + String value = randomMockFlag ? RandomUtil.randomValueByType(type) + : RandomUtil.generateDefaultValueByType(type); if (javaPrimaryType(type)) { return value; } @@ -1067,7 +1084,7 @@ else if (clzz.isInterface()) { } } catch (ClassNotFoundException e) { - e.printStackTrace(); + logger.warning(e.getMessage()); } return new ArrayList<>(errorCodeList); } @@ -1149,7 +1166,7 @@ public static List buildDictionary(ApiConfig config, JavaProjectBuil } } catch (ClassNotFoundException e) { - e.printStackTrace(); + logger.warning(e.getMessage()); } return apiDocDictList; } diff --git a/src/main/java/com/ly/doc/utils/HttpStatusUtil.java b/src/main/java/com/ly/doc/utils/HttpStatusUtil.java index 53333a65..2f98b00c 100644 --- a/src/main/java/com/ly/doc/utils/HttpStatusUtil.java +++ b/src/main/java/com/ly/doc/utils/HttpStatusUtil.java @@ -23,11 +23,20 @@ import com.ly.doc.constants.HttpStatusEnum; /** + * HttpStatusUtil + * * @author yu.sun on 2024/6/9 * @since 3.0.5 */ public class HttpStatusUtil { + /** + * private constructor + */ + private HttpStatusUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Retrieves the corresponding HTTP status code as a string based on the input status * string. This method maps status strings from the HttpStatus enum to their numeric diff --git a/src/main/java/com/ly/doc/utils/Iterables.java b/src/main/java/com/ly/doc/utils/Iterables.java index f85497f7..a7c78fbe 100644 --- a/src/main/java/com/ly/doc/utils/Iterables.java +++ b/src/main/java/com/ly/doc/utils/Iterables.java @@ -21,15 +21,30 @@ * under the License. */ -/** - * @author daiww 2020/08/26. - */ package com.ly.doc.utils; import java.util.function.BiConsumer; +/** + * Iterables + * + * @author daiww + */ public class Iterables { + /** + * private constructor + */ + private Iterables() { + throw new IllegalStateException("Utility class"); + } + + /** + * forEach + * @param elements elements + * @param action action + * @param E + */ public static void forEach(Iterable elements, BiConsumer action) { if (elements == null || action == null) { return; diff --git a/src/main/java/com/ly/doc/utils/JavaClassUtil.java b/src/main/java/com/ly/doc/utils/JavaClassUtil.java index 9fa99107..ff311fa9 100644 --- a/src/main/java/com/ly/doc/utils/JavaClassUtil.java +++ b/src/main/java/com/ly/doc/utils/JavaClassUtil.java @@ -60,6 +60,13 @@ public class JavaClassUtil { */ private static final Logger logger = Logger.getLogger(JavaClassUtil.class.getName()); + /** + * private constructor + */ + private JavaClassUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Get fields * @param cls1 The JavaClass object @@ -368,7 +375,7 @@ private static Class loadEnumClass(JavaClass javaClass, ProjectDocConfigBuild } } catch (ClassNotFoundException e) { - e.printStackTrace(); + logger.warning(e.getMessage()); return null; } } @@ -439,6 +446,11 @@ private static Object processDefaultEnumFields(List javaFields, boole return value; } + /** + * Gets the enum parameters for the given JavaClass. + * @param javaClass The JavaClass representing the enum + * @return A String containing the enum parameters + */ public static String getEnumParams(JavaClass javaClass) { List javaFields = javaClass.getEnumConstants(); StringBuilder stringBuilder = new StringBuilder(); @@ -466,6 +478,16 @@ public static List getEnumValues(JavaClass javaClass) { return enums; } + /** + * Retrieves the associated enum class for a given Java field. + *

+ * This method aims to obtain the enum type (JavaClass) associated with the provided + * Java field object (JavaField). If the field does not associate with an enum type or + * if there is no appropriate @see tag providing enum information, it returns null. + * @param javaField The Java field object to inspect + * @param builder The builder used to retrieve project documentation configuration + * @return The enum class object associated with the field, or null if not found + */ public static JavaClass getSeeEnum(JavaField javaField, ProjectDocConfigBuilder builder) { if (Objects.isNull(javaField)) { return null; @@ -701,6 +723,17 @@ public static Set getParamGroupJavaClass(JavaAnnotation javaAnnotation) return javaClassList; } + /** + * Retrieves the Javadoc tag values for a specified tag name in a given Java class. + * @param cls The Java class to inspect. + * @param tagName The name of the tag to search for. + * @param checkComments Indicates whether to validate the presence of comments for + * empty tag values. + * @return A comma-separated string of all values found for the specified tag, or an + * empty string if the tag name is empty. + * @throws RuntimeException If the tag is used without comments and checkComments is + * true. + */ public static String getClassTagsValue(final JavaClass cls, final String tagName, boolean checkComments) { if (StringUtil.isNotEmpty(tagName)) { StringBuilder result = new StringBuilder(); @@ -748,6 +781,11 @@ public static Map getFinalFieldValue(Class clazz) throws Ille return constants; } + /** + * Add group class + * @param annotationValueList annotation value list + * @param javaClassList java class list + */ private static void addGroupClass(List annotationValueList, Set javaClassList) { if (CollectionUtil.isEmpty(annotationValueList)) { return; @@ -759,6 +797,12 @@ private static void addGroupClass(List annotationValueList, Set } } + /** + * Add group class + * @param annotationValueList annotation value list + * @param javaClassList java class list + * @param builder JavaProjectBuilder + */ private static void addGroupClass(List annotationValueList, Set javaClassList, JavaProjectBuilder builder) { if (CollectionUtil.isEmpty(annotationValueList)) { @@ -774,6 +818,12 @@ private static void addGroupClass(List annotationValueList, Set } } + /** + * Recursively adds all valid interfaces to the provided set. + * @param classByName The Java class to start the recursion from. + * @param javaClassSet The set to which valid interfaces will be added. + * @param builder The JavaProjectBuilder instance used for class lookup. + */ private static void recursionGetAllValidInterface(JavaClass classByName, Set javaClassSet, JavaProjectBuilder builder) { List anImplements = classByName.getImplements(); @@ -830,6 +880,12 @@ else if (validates.contains(simpleName)) { return Collections.emptyList(); } + /** + * Generic parameter map. + * @param genericMap generic map + * @param cls Java class + * @param globGicName generic name array + */ public static void genericParamMap(Map genericMap, JavaClass cls, String[] globGicName) { if (Objects.isNull(cls) || Objects.isNull(cls.getTypeParameters())) { return; diff --git a/src/main/java/com/ly/doc/utils/JavaClassValidateUtil.java b/src/main/java/com/ly/doc/utils/JavaClassValidateUtil.java index 5c92b141..70a4d835 100644 --- a/src/main/java/com/ly/doc/utils/JavaClassValidateUtil.java +++ b/src/main/java/com/ly/doc/utils/JavaClassValidateUtil.java @@ -36,10 +36,22 @@ import static com.ly.doc.constants.JsonPropertyAnnotationAccessConstants.JSON_PROPERTY_WRITE_ONLY; /** + * Java Class Validate Util + * * @author yu 2019/12/25. */ public class JavaClassValidateUtil { + /** + * private constructor + */ + private JavaClassValidateUtil() { + throw new IllegalStateException("Utility class"); + } + + /** + * class pattern + */ private static final String CLASS_PATTERN = "^([A-Za-z]{1}[A-Za-z\\d_]*\\.)+[A-Za-z][A-Za-z\\d_]*$"; /** @@ -215,12 +227,7 @@ public static boolean isJSR303Required(String annotationSimpleName) { * @return boolean */ public static boolean isIgnoreTag(String tagName) { - switch (tagName) { - case "ignore": - return true; - default: - return false; - } + return tagName.equals("ignore"); } /** @@ -355,6 +362,11 @@ public static boolean ignoreSpringMvcParamWithAnnotation(String annotation) { } } + /** + * ignore param with annotation + * @param annotation Solon Mvc annotation + * @return boolean + */ public static boolean ignoreSolonMvcParamWithAnnotation(String annotation) { switch (annotation) { case SolonAnnotations.REQUEST_HERDER: @@ -387,12 +399,18 @@ public static boolean isClassName(String className) { if (className.contains("<") && !className.contains(">")) { return false; } - else if (className.contains(">") && !className.contains("<")) { - return false; + else { + return !className.contains(">") || className.contains("<"); } - return true; + } + /** + * is ignore field json + * @param annotation annotation + * @param isResp isResp + * @return true or false + */ public static boolean isIgnoreFieldJson(JavaAnnotation annotation, Boolean isResp) { String simpleAnnotationName = annotation.getType().getValue(); if (DocAnnotationConstants.SHORT_JSON_IGNORE.equals(simpleAnnotationName)) { @@ -415,9 +433,7 @@ public static boolean isIgnoreFieldJson(JavaAnnotation annotation, Boolean isRes if (!isResp && Objects.nonNull(deserialize) && Boolean.FALSE.toString().equals(deserialize.toString())) { return true; } - if (isResp && Objects.nonNull(serialize) && Boolean.FALSE.toString().equals(serialize.toString())) { - return true; - } + return isResp && Objects.nonNull(serialize) && Boolean.FALSE.toString().equals(serialize.toString()); } return false; } diff --git a/src/main/java/com/ly/doc/utils/JavaFieldUtil.java b/src/main/java/com/ly/doc/utils/JavaFieldUtil.java index 7084be2f..99b7f3e5 100644 --- a/src/main/java/com/ly/doc/utils/JavaFieldUtil.java +++ b/src/main/java/com/ly/doc/utils/JavaFieldUtil.java @@ -22,7 +22,10 @@ */ package com.ly.doc.utils; -import com.ly.doc.constants.*; +import com.ly.doc.constants.DocGlobalConstants; +import com.ly.doc.constants.DocValidatorAnnotationEnum; +import com.ly.doc.constants.JSRAnnotationConstants; +import com.ly.doc.constants.JSRAnnotationPropConstants; import com.ly.doc.model.CustomField; import com.ly.doc.model.DocJavaField; import com.power.common.util.StringUtil; @@ -37,16 +40,26 @@ import java.util.Objects; /** + * JavaFieldUtil + * * @author yu 2019/12/21. */ public class JavaFieldUtil { + /** + * private constructor + */ + private JavaFieldUtil() { + throw new IllegalStateException("Utility class"); + } + /** * public static final */ private static final int PUBLIC_STATIC_FINAL = Modifier.PUBLIC | Modifier.STATIC | Modifier.FINAL; /** + * check generics * @param fields list of fields * @return boolean */ @@ -60,6 +73,7 @@ public static boolean checkGenerics(List fields) { } /** + * build custom field * @param data0 data0 * @param typeSimpleName typeName * @param customField config field @@ -77,6 +91,7 @@ public static void buildCustomField(StringBuilder data0, String typeSimpleName, } /** + * create mock value * @param paramsComments param comments * @param paramName param name * @param typeName param type @@ -102,6 +117,7 @@ public static String createMockValue(Map paramsComments, String } /** + * get param max length * @param annotations annotation * @return max length */ @@ -167,6 +183,11 @@ public static String getJsrComment(boolean showValidation, ClassLoader classLoad return "\nValidation[" + sb + "]"; } + /** + * convert to simple type name + * @param str str + * @return simple type name + */ public static String convertToSimpleTypeName(String str) { String regex = "\\b\\w+\\.(?=\\w+\\b)"; return str.replaceAll(regex, ""); diff --git a/src/main/java/com/ly/doc/utils/JsonUtil.java b/src/main/java/com/ly/doc/utils/JsonUtil.java index 39e80d35..de0df2b7 100644 --- a/src/main/java/com/ly/doc/utils/JsonUtil.java +++ b/src/main/java/com/ly/doc/utils/JsonUtil.java @@ -30,10 +30,19 @@ import java.util.Objects; /** + * Json Util + * * @author yu 2021/6/26. */ public class JsonUtil { + /** + * private constructor + */ + private JsonUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Convert a JSON string to pretty print * @param jsonString json string @@ -66,6 +75,13 @@ public static String toPrettyJson(Object src) { return gson.toJson(src); } + /** + * Convert a JSON string to object + * @param type + * @param json json string + * @param clazz class + * @return Object + */ public static T toObject(String json, Class clazz) { return new Gson().fromJson(json, clazz); } diff --git a/src/main/java/com/ly/doc/utils/OpenApiSchemaUtil.java b/src/main/java/com/ly/doc/utils/OpenApiSchemaUtil.java index 16f93d41..e79de627 100644 --- a/src/main/java/com/ly/doc/utils/OpenApiSchemaUtil.java +++ b/src/main/java/com/ly/doc/utils/OpenApiSchemaUtil.java @@ -22,14 +22,6 @@ */ package com.ly.doc.utils; -import java.util.ArrayList; -import java.util.HashMap; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Map; -import java.util.regex.Matcher; -import java.util.regex.Pattern; - import com.ly.doc.constants.ComponentTypeEnum; import com.ly.doc.constants.DocGlobalConstants; import com.ly.doc.model.ApiConfig; @@ -38,40 +30,78 @@ import com.power.common.util.StringUtil; import org.apache.commons.codec.digest.DigestUtils; +import java.util.*; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + import static com.ly.doc.constants.TornaConstants.GSON; /** + * OpenApi Schema Util + * * @author yu 2020/11/29. */ public class OpenApiSchemaUtil { + /** + * private constructor + */ + private OpenApiSchemaUtil() { + throw new IllegalStateException("Utility class"); + } + + /** + * No body param + */ public static final String NO_BODY_PARAM = "NO_BODY_PARAM"; + + /** + * Pattern + */ static final Pattern PATTERN = Pattern.compile("[A-Z]\\w+.*?|[A-Z]"); + /** + * Primary type schema + * @param primaryType primary type + * @return Map + */ public static Map primaryTypeSchema(String primaryType) { Map map = new HashMap<>(16); map.put("type", DocUtil.javaTypeToOpenApiTypeConvert(primaryType)); return map; } + /** + * Map type schema + * @param primaryType primary type + * @return Map + */ public static Map mapTypeSchema(String primaryType) { Map map = new LinkedHashMap<>(); map.put("type", "object"); - Map items = new HashMap<>(16); - items.put("type", DocUtil.javaTypeToOpenApiTypeConvert(primaryType)); + Map items = primaryTypeSchema(primaryType); map.put("additionalProperties", items); return map; } + /** + * Array type schema + * @param primaryType primary type + * @return Map + */ public static Map arrayTypeSchema(String primaryType) { Map map = new HashMap<>(16); map.put("type", "array"); - Map items = new HashMap<>(16); - items.put("type", DocUtil.javaTypeToOpenApiTypeConvert(primaryType)); + Map items = primaryTypeSchema(primaryType); map.put("items", items); return map; } + /** + * Get className from params + * @param apiParams api params + * @return className + */ public static String getClassNameFromParams(List apiParams) { ComponentTypeEnum componentTypeEnum = ApiConfig.getInstance().getComponentType(); // random name @@ -93,10 +123,21 @@ public static String getClassNameFromParams(List apiParams) { return NO_BODY_PARAM; } + /** + * Delete className + * @param className className + * @return className + */ public static String delClassName(String className) { return String.join("", getPatternResult(PATTERN, className)); } + /** + * Get pattern result + * @param p pattern + * @param content content + * @return result + */ public static List getPatternResult(Pattern p, String content) { List matchers = new ArrayList<>(); Matcher m = p.matcher(content); @@ -106,14 +147,15 @@ public static List getPatternResult(Pattern p, String content) { return matchers; } + /** + * Get pattern result + * @param rex regex + * @param content content + * @return result + */ public static List getPatternResult(String rex, String content) { Pattern p = Pattern.compile(rex); - List matchers = new ArrayList<>(); - Matcher m = p.matcher(content); - while (m.find()) { - matchers.add(m.group()); - } - return matchers; + return getPatternResult(p, content); } } diff --git a/src/main/java/com/ly/doc/utils/ParamUtil.java b/src/main/java/com/ly/doc/utils/ParamUtil.java index 0d2353cc..552a6df6 100644 --- a/src/main/java/com/ly/doc/utils/ParamUtil.java +++ b/src/main/java/com/ly/doc/utils/ParamUtil.java @@ -14,11 +14,20 @@ import java.util.stream.IntStream; /** + * ParamUtil + * * @author chenqi * @version 1.0 */ public class ParamUtil { + /** + * private constructor + */ + private ParamUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Handles enum types in API parameters. *

@@ -73,6 +82,11 @@ public static JavaClass handleSeeEnum(ApiParam param, JavaField javaField, Proje return seeEnum; } + /** + * Format mock value + * @param mock mock value + * @return formatted mock value + */ public static String formatMockValue(String mock) { if (StringUtil.isEmpty(mock)) { return mock; @@ -80,6 +94,11 @@ public static String formatMockValue(String mock) { return mock.replaceAll("\\\\", ""); } + /** + * Extract qualified name from param list + * @param paramList param list + * @return qualified name list + */ public static List extractQualifiedName(List paramList) { if (CollectionUtil.isEmpty(paramList)) { return Collections.emptyList(); diff --git a/src/main/java/com/ly/doc/utils/RequestExampleUtil.java b/src/main/java/com/ly/doc/utils/RequestExampleUtil.java index bb80f5ca..9476a227 100644 --- a/src/main/java/com/ly/doc/utils/RequestExampleUtil.java +++ b/src/main/java/com/ly/doc/utils/RequestExampleUtil.java @@ -18,12 +18,19 @@ import java.util.stream.Collectors; /** - * write on a plane + * RequestExampleUtil (write on a plane) * * @author yu 2024/05/27. */ public class RequestExampleUtil { + /** + * private constructor + */ + private RequestExampleUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Sets example data into the API method documentation. * @param apiMethodDoc The API method documentation object to receive the example diff --git a/src/main/java/com/ly/doc/utils/TornaUtil.java b/src/main/java/com/ly/doc/utils/TornaUtil.java index f80c1ee3..5f284cf7 100644 --- a/src/main/java/com/ly/doc/utils/TornaUtil.java +++ b/src/main/java/com/ly/doc/utils/TornaUtil.java @@ -51,6 +51,13 @@ **/ public class TornaUtil { + /** + * private constructor + */ + private TornaUtil() { + throw new IllegalStateException("Utility class"); + } + /** * Pushes documentation to the Torna API documentation platform. *