Merge pull request #1019 from linwumingshi/refactor/javadoc

refactor(doc): 🎨 improve API documentation generation and enforce strict `Javadoc` validation

Author: shalousun

pom.xml

@@ -129,8 +129,30 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>${maven-javadoc-plugin.version}</version>
+                <configuration>
+                    <!--
+                    Fail the build if any Javadoc warnings or errors occur.
+                    This ensures that all Javadoc issues are treated seriously.
+                    -->
+                    <failOnError>true</failOnError>
+                    <additionalOptions>
+                        <!--
+                        Enable strict validation of Javadoc content.
+                        The "all" option checks for syntax, references, and HTML issues.
+                        -->
+                        <additionalOption>-Xdoclint:all</additionalOption>
+                    </additionalOptions>
+                </configuration>
                 <executions>
                     <execution>
+                        <id>validate-javadoc</id>
+                        <phase>validate</phase>
+                        <goals>
+                            <goal>javadoc</goal>
+                        </goals>
+                    </execution>
+                    <execution>
+                        <id>package-javadoc-jar</id>
                         <phase>package</phase>
                         <goals>
                             <goal>jar</goal>

src/main/java/com/ly/doc/builder/IRpcDocBuilderTemplate.java

@@ -130,6 +130,7 @@ default void buildAllInOne(List<T> apiDocList, ApiConfig config, JavaProjectBuil
 	 * @param javaProjectBuilder JavaProjectBuilder
 	 * @param template template
 	 * @param outPutFileName output file
+	 * @return beetl Template
 	 */
 	default Template buildAllInOneWord(List<RpcApiDoc> apiDocList, ApiConfig config,
 			JavaProjectBuilder javaProjectBuilder, String template, String outPutFileName) {

src/main/java/com/ly/doc/template/IRestDocTemplate.java

@@ -1214,7 +1214,7 @@ else if (JavaClassValidateUtil.isFile(gicName)) {
 					paramList.add(param);
 				}
 				else {
-					if (requestBodyCounter > 0 || !ApiParamEnum.QUERY.equals(apiParamEnum)) {
+					if (requestBodyCounter > 0 || !isQueryParam) {
 						// for json
 						paramList.addAll(ParamsBuildHelper.buildParams(gicNameArr[0], DocGlobalConstants.EMPTY, 0,
 								String.valueOf(required), Boolean.FALSE, new HashMap<>(16), builder, groupClasses,
@@ -1305,6 +1305,7 @@ else if (isRequestPart) {
 						String.valueOf(required), Boolean.FALSE, new HashMap<>(16), builder, groupClasses,
 						docJavaMethod.getJsonViewClasses(), 1, jsonRequest, null));
 			}
+			// other types
 			else {
 				List<ApiParam> apiParams = ParamsBuildHelper.buildParams(typeName, DocGlobalConstants.EMPTY, 0,
 						String.valueOf(required), Boolean.FALSE, new HashMap<>(16), builder, groupClasses,
@@ -1313,7 +1314,7 @@ else if (isRequestPart) {
 				boolean hasFile = apiParams.stream()
 					.anyMatch(param -> ParamTypeConstants.PARAM_TYPE_FILE.equals(param.getType()));
 				// if it does not have file and query param, set query param true
-				if (!hasFile && ApiParamEnum.QUERY.equals(apiParamEnum)) {
+				if (!hasFile && isQueryParam) {
 					for (ApiParam apiParam : apiParams) {
 						apiParam.traverseAndConsume(ApiParam::setQueryParamTrue);
 					}