Merge pull request #708 from linwumingshi/master

feat: don't create config file when the increment is false
TongchengOpenSource · Jan 21, 2024 · 23bebd2 · 23bebd2
2 parents 37e4ac7 + c3929bc
commit 23bebd2
Show file tree

Hide file tree

Showing 11 changed files with 103 additions and 56 deletions.
diff --git a/src/main/java/com/ly/doc/builder/DocBuilderTemplate.java b/src/main/java/com/ly/doc/builder/DocBuilderTemplate.java
@@ -95,6 +95,7 @@ public void buildApiDoc(List<ApiDoc> apiDocList, ApiConfig config, String templa
      * @param doc      api doc
      * @param config   api config
      * @param template template
+     * @return Template
      */
     public Template buildApiDocTemplate(ApiDoc doc, ApiConfig config, String template) {
         Template mapper = BeetlTemplateUtil.getByName(template);
@@ -130,6 +131,7 @@ public void buildAllInOne(List<ApiDoc> apiDocList, ApiConfig config, JavaProject
      * @param template           template
      * @param apiDoc             apiDoc
      * @param index              index html
+     * @return Template
      */
     public Template buildAllRenderDocTemplate(List<ApiDoc> apiDocList, ApiConfig config, JavaProjectBuilder javaProjectBuilder,
                                               String template, ApiDoc apiDoc, String index) {
@@ -305,6 +307,7 @@ public void buildErrorCodeDoc(ApiConfig config, String template, String outPutFi
      * @param config             api config
      * @param template           template
      * @param javaProjectBuilder javaProjectBuilder
+     * @return template
      */
     public Template buildErrorCodeDocTemplate(ApiConfig config, String template, JavaProjectBuilder javaProjectBuilder) {
         List<ApiErrorCode> errorCodeList = DocUtil.errorCodeDictToList(config, javaProjectBuilder);
@@ -418,6 +421,7 @@ public void buildDirectoryDataDoc(ApiConfig config, JavaProjectBuilder javaProje
      * @param config             api config
      * @param javaProjectBuilder JavaProjectBuilder
      * @param template           template
+     * @return Template
      */
     public Template buildDirectoryDataDocTemplate(ApiConfig config, JavaProjectBuilder javaProjectBuilder, String template) {
         List<ApiDocDict> directoryList = DocUtil.buildDictionary(config, javaProjectBuilder);

diff --git a/src/main/java/com/ly/doc/builder/WordDocBuilder.java b/src/main/java/com/ly/doc/builder/WordDocBuilder.java
@@ -57,6 +57,7 @@ public class WordDocBuilder {
      * build controller api
      *
      * @param config config
+     * @throws Exception exception
      */
     public static void buildApiDoc(ApiConfig config) throws Exception {
         JavaProjectBuilder javaProjectBuilder = JavaProjectBuilderHelper.create();
@@ -67,6 +68,8 @@ public static void buildApiDoc(ApiConfig config) throws Exception {
      * build controller api
      *
      * @param config config
+     * @param javaProjectBuilder javaProjectBuilder
+     * @throws Exception exception
      */
     public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectBuilder) throws Exception {
         DocBuilderTemplate builderTemplate = new DocBuilderTemplate();
@@ -105,6 +108,7 @@ public static void buildApiDoc(ApiConfig config, JavaProjectBuilder javaProjectB
      *
      * @param content        doc content
      * @param docxOutputPath docx output path
+     * @throws Exception exception
      * @since 1.0.0
      */
     public static void copyAndReplaceDocx(String content, String docxOutputPath) throws Exception {
@@ -118,7 +122,7 @@ public static void copyAndReplaceDocx(String content, String docxOutputPath) thr
         while ((entry = zipInputStream.getNextEntry()) != null) {
             String entryName = entry.getName();
 
-            if (entryName.equals("word/document.xml")) {
+            if ("word/document.xml".equals(entryName)) {
                 zipOutputStream.putNextEntry(new ZipEntry(entryName));
                 byte[] bytes = content.getBytes(StandardCharsets.UTF_8);
                 zipOutputStream.write(bytes, 0, bytes.length);

diff --git a/src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java b/src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java
@@ -24,18 +24,18 @@
 
 package com.ly.doc.builder.openapi;
 
-import com.ly.doc.constants.ComponentTypeEnum;
-import com.ly.doc.model.*;
-import com.power.common.util.CollectionUtil;
-import com.power.common.util.StringUtil;
 import com.ly.doc.builder.DocBuilderTemplate;
 import com.ly.doc.builder.ProjectDocConfigBuilder;
+import com.ly.doc.constants.ComponentTypeEnum;
 import com.ly.doc.constants.DocGlobalConstants;
 import com.ly.doc.factory.BuildTemplateFactory;
+import com.ly.doc.model.*;
 import com.ly.doc.model.openapi.OpenApiTag;
 import com.ly.doc.template.IDocBuildTemplate;
 import com.ly.doc.utils.DocUtil;
 import com.ly.doc.utils.OpenApiSchemaUtil;
+import com.power.common.util.CollectionUtil;
+import com.power.common.util.StringUtil;
 import com.thoughtworks.qdox.JavaProjectBuilder;
 
 import java.util.*;
@@ -85,6 +85,8 @@ public void setComponentKey(String componentKey) {
      * response body
      *
      * @param apiMethodDoc ApiMethodDoc
+     * @param apiConfig    ApiConfig
+     * @return Map of response body
      */
     abstract Map<String, Object> buildResponsesBody(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc);
 
@@ -101,13 +103,14 @@ public void setComponentKey(String componentKey) {
      * @param apiConfig  Configuration of smart-doc
      * @param apiDocList List of API DOC
      * @param tags       tags
+     * @return Map of paths
      */
     public Map<String, Object> buildPaths(ApiConfig apiConfig, List<ApiDoc> apiDocList, Set<OpenApiTag> tags) {
         Map<String, Object> pathMap = new HashMap<>(500);
         Set<ApiMethodDoc> methodDocs = DocMapping.METHOD_DOCS;
         for (ApiMethodDoc methodDoc : methodDocs) {
-            String [] paths = methodDoc.getPath().split(";");
-            for(String path : paths) {
+            String[] paths = methodDoc.getPath().split(";");
+            for (String path : paths) {
                 path = path.trim();
                 Map<String, Object> request = buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc());
                 if (!pathMap.containsKey(path)) {
@@ -135,6 +138,7 @@ public Map<String, Object> buildPaths(ApiConfig apiConfig, List<ApiDoc> apiDocLi
      * @param apiConfig    ApiConfig
      * @param apiMethodDoc Method
      * @param apiDoc       ApiDoc
+     * @return Map of path urls
      */
     public Map<String, Object> buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, ApiDoc apiDoc) {
         Map<String, Object> request = new HashMap<>(4);
@@ -148,6 +152,7 @@ public Map<String, Object> buildPathUrls(ApiConfig apiConfig, ApiMethodDoc apiMe
      * @param apiConfig    ApiConfig
      * @param apiMethodDoc ApiMethodDoc
      * @param isRep        is response
+     * @return Map of content
      */
     public Map<String, Object> buildContent(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, boolean isRep) {
         Map<String, Object> content = new HashMap<>(8);
@@ -166,6 +171,7 @@ public Map<String, Object> buildContent(ApiConfig apiConfig, ApiMethodDoc apiMet
      * @param apiConfig    ApiConfig
      * @param apiMethodDoc ApiMethodDoc
      * @param isRep        is response
+     * @return Map of content
      */
     public Map<String, Object> buildContentBody(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc, boolean isRep) {
         Map<String, Object> content = new HashMap<>(8);
@@ -193,6 +199,7 @@ public Map<String, Object> buildContentBody(ApiConfig apiConfig, ApiMethodDoc ap
      *
      * @param apiMethodDoc ApiMethodDoc
      * @param isRep        is response
+     * @return Map of schema
      */
     public Map<String, Object> buildBodySchema(ApiMethodDoc apiMethodDoc, boolean isRep) {
         Map<String, Object> schema = new HashMap<>(10);
@@ -237,6 +244,7 @@ public Map<String, Object> buildBodySchema(ApiMethodDoc apiMethodDoc, boolean is
      *
      * @param apiMethodDoc ApiMethodDoc
      * @param isRep        is response
+     * @return Map of content
      */
     public static Map<String, Object> buildBodyExample(ApiMethodDoc apiMethodDoc, boolean isRep) {
         Map<String, Object> content = new HashMap<>(8);
@@ -250,6 +258,7 @@ public static Map<String, Object> buildBodyExample(ApiMethodDoc apiMethodDoc, bo
      *
      * @param apiMethodDoc ApiMethodDoc
      * @param isRep        is response
+     * @return Map of content
      */
     public static Map<String, Object> buildExampleData(ApiMethodDoc apiMethodDoc, boolean isRep) {
         Map<String, Object> content = new HashMap<>(8);
@@ -314,6 +323,7 @@ public Map<String, Object> buildParametersSchema(ApiParam apiParam) {
      * If the header is included, set the request parameters
      *
      * @param header header
+     * @return parameters schema
      */
     public static Map<String, Object> buildParametersSchema(ApiReqParam header) {
         Map<String, Object> schema = new HashMap<>(10);
@@ -327,6 +337,7 @@ public static Map<String, Object> buildParametersSchema(ApiReqParam header) {
      * build response
      *
      * @param apiMethodDoc ApiMethodDoc
+     * @param apiConfig    ApiConfig
      * @return response info
      */
     public Map<String, Object> buildResponses(ApiConfig apiConfig, ApiMethodDoc apiMethodDoc) {
@@ -339,13 +350,17 @@ public Map<String, Object> buildResponses(ApiConfig apiConfig, ApiMethodDoc apiM
      * component schema
      *
      * @param apiDocs List of ApiDoc
+     * @return component schema Map
      */
     abstract public Map<String, Object> buildComponentsSchema(List<ApiDoc> apiDocs);
 
     /**
      * component schema properties
      *
-     * @param apiParam list of ApiParam
+     * @param apiParam  list of ApiParam
+     * @param component component
+     * @param isResp    is response
+     * @return properties
      */
     public Map<String, Object> buildProperties(List<ApiParam> apiParam, Map<String, Object> component, boolean isResp) {
         Map<String, Object> properties = new HashMap<>();
@@ -454,6 +469,7 @@ private Map<String, Object> buildPropertiesData(ApiParam apiParam, Map<String, O
      *
      * @param config         Configuration of smart-doc
      * @param projectBuilder JavaDocBuilder of QDox
+     * @return List of OpenAPI's document data
      */
     public List<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder projectBuilder) {
         config.setShowJavaType(false);

diff --git a/src/main/java/com/ly/doc/extension/dict/DictionaryValuesResolver.java b/src/main/java/com/ly/doc/extension/dict/DictionaryValuesResolver.java
@@ -35,6 +35,7 @@ public interface DictionaryValuesResolver {
      * default behaviour is the same as {@link #resolve()}
      *
      * @param clazz dictionary class
+     * @param <T>   the type parameter
      * @return the dictionary
      */
     default <T extends EnumDictionary> Collection<T> resolve(Class<?> clazz) {
@@ -45,6 +46,8 @@ default <T extends EnumDictionary> Collection<T> resolve(Class<?> clazz) {
      * resolve the dictionary, for compatibility, do not return null
      *
      * @see #resolve(Class)
+     * @param <T> the type parameter
+     * @return the dictionary
      */
     default <T extends EnumDictionary> Collection<T> resolve() {
         return Collections.emptyList();

diff --git a/src/main/java/com/ly/doc/helper/DocBuildHelper.java b/src/main/java/com/ly/doc/helper/DocBuildHelper.java
@@ -82,8 +82,9 @@ public static DocBuildHelper create(ProjectDocConfigBuilder configBuilder) {
         DocBuildHelper helper = new DocBuildHelper();
         helper.projectBuilder = configBuilder.getJavaProjectBuilder();
         helper.codePath = codePath;
+        // when is git repo
         if (helper.gitHelper.isGitRepo()) {
-            helper.dependencyTree = DependencyTree.detect(baseDir);
+            helper.dependencyTree = DependencyTree.detect(baseDir, apiConfig.isIncrement());
         }
 
         return helper;
@@ -157,7 +158,7 @@ private List<ApiDependency> mergeDependencyTree(List<ApiDependency> newDependenc
                 deletedClazz.contains(dependency.getClazz())
                         || deprecatedClazz.contains(dependency.getClazz())
                         || deprecatedClazz.stream().anyMatch(deprecate ->
-                            dependency.getDerivedClazz().contains(deprecate))
+                        dependency.getDerivedClazz().contains(deprecate))
         );
 
         // replace the old dependency tree with new dependency
@@ -185,12 +186,15 @@ private List<ApiDependency> mergeDependencyTree(List<ApiDependency> newDependenc
 
     /**
      * Find and gather classes and their dependencies.
-     * <br/>
+     * <p>
      * When a class is modified within the git tree, and it is part of an endpoint argument or return value,
      * this method will also include the classes containing these endpoints classes.
-     * <br/>
+     * <p>
      * If all modified classes are not part of the API dependency tree (e.g., they are services or mappers),
      * this method will return an empty collection, as they do not impact the API documentation.
+     *
+     * @param isEntryPoint the entry point predicate
+     * @return the set of changed files
      */
     public Set<FileDiff> getChangedFilesFromVCS(Predicate<String> isEntryPoint) {
         String commitId = dependencyTree.getCommitId();

diff --git a/src/main/java/com/ly/doc/model/ApiConfig.java b/src/main/java/com/ly/doc/model/ApiConfig.java
@@ -20,17 +20,17 @@
  */
 package com.ly.doc.model;
 
+import com.ly.doc.constants.ComponentTypeEnum;
+import com.ly.doc.constants.DocLanguage;
+import com.ly.doc.handler.ICustomJavaMethodHandler;
+import com.ly.doc.model.rpc.RpcApiDependency;
+import com.power.common.util.CollectionUtil;
+
 import java.util.List;
 import java.util.Objects;
 import java.util.Set;
 import java.util.stream.Collectors;
 
-import com.ly.doc.constants.ComponentTypeEnum;
-import com.ly.doc.model.rpc.RpcApiDependency;
-import com.power.common.util.CollectionUtil;
-import com.ly.doc.constants.DocLanguage;
-import com.ly.doc.handler.ICustomJavaMethodHandler;
-
 /**
  * Description:
  * api config info
@@ -367,14 +367,17 @@ public class ApiConfig {
 
     /**
      * build random component for openApi
+     *
      * @see ComponentTypeEnum
      */
     private ComponentTypeEnum componentType = ComponentTypeEnum.RANDOM;
 
     /**
      * whether to build the doc incrementally
+     *
+     * @since 3.0.0
      */
-    private boolean increment;
+    private boolean increment = Boolean.FALSE;
 
     /**
      * the doc module absolute path, used for dependency tree file
@@ -383,6 +386,7 @@ public class ApiConfig {
 
     /**
      * upload api split number
+     *
      * @since 3.0.2
      */
     private Integer apiUploadNums;

diff --git a/src/main/java/com/ly/doc/model/IDoc.java b/src/main/java/com/ly/doc/model/IDoc.java
@@ -29,11 +29,13 @@ public interface IDoc {
 
     /**
      * doc class qualified name
+     * @return class qualified name
      */
     String getDocClass();
 
     /**
-     *
+     * get doc methods
+     * @return methods
      */
     List<IMethod> getMethods();
 

diff --git a/src/main/java/com/ly/doc/model/dependency/DependencyTree.java b/src/main/java/com/ly/doc/model/dependency/DependencyTree.java
@@ -68,17 +68,24 @@ private DependencyTree() {
      * Create or Load dependency tree config.
      *
      * @param baseDir the dependency tree config file base directory
+     * @param isIncrement whether increment build
      * @return DependencyTree
      */
-    public static DependencyTree detect(String baseDir) {
+    public static DependencyTree detect(String baseDir, boolean isIncrement) {
         DependencyTree dependencyTree;
 
         File configFile = new File(baseDir + File.separator + CONFIG_NAME);
-        if (!configFile.exists()) {
+        // the config file no exists
+        boolean fileNoExists = !configFile.exists();
+        if (fileNoExists) {
             dependencyTree = Support.create(configFile);
         } else {
             dependencyTree = Support.load(configFile);
         }
+        // if file no exists, and not increment build, delete the config file after build
+        if (fileNoExists && !isIncrement) {
+            configFile.delete();
+        }
 
         return dependencyTree;
     }

diff --git a/src/main/java/com/ly/doc/utils/DocUtil.java b/src/main/java/com/ly/doc/utils/DocUtil.java
@@ -1197,7 +1197,7 @@ public static boolean substringMatch(CharSequence str, int index, CharSequence s
      * split url by '/'
      * example: ${server.error.path:${error.path:/error}}/test/{name:[a-zA-Z0-9]{3}}/{bb}/add
      *
-     * @param url
+     * @param url url
      * @return List of path
      */
     public static List<String> splitPathBySlash(String url) {

diff --git a/src/main/java/com/ly/doc/utils/JavaClassUtil.java b/src/main/java/com/ly/doc/utils/JavaClassUtil.java
@@ -59,6 +59,7 @@ public class JavaClassUtil {
      * @param cls1        The JavaClass object
      * @param counter     Recursive counter
      * @param addedFields added fields,Field deduplication
+     * @param classLoader classLoader
      * @return list of JavaField
      */
     public static List<DocJavaField> getFields(JavaClass cls1, int counter, Map<String, DocJavaField> addedFields, ClassLoader classLoader) {