parent afb76ed

author dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> 1740961143 +0000
committer xingzi <[email protected]> 1747553933 +0800

parent afb76ed
author dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> 1740961143 +0000
committer xingzi <[email protected]> 1747553897 +0800

chore(deps): bump com.ibeetl:beetl from 3.19.0.RELEASE to 3.19.1.RELEASE

Bumps com.ibeetl:beetl from 3.19.0.RELEASE to 3.19.1.RELEASE.

---
updated-dependencies:
- dependency-name: com.ibeetl:beetl
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <[email protected]>

Author: dependabot[bot]

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thank you for your interest in contributing to `smart-doc`! For detailed guidelines on how to contribute, please review our official [**Contribution Guide**](https://smart-doc-group.github.io/guide/community/contributing).
+
+## Key Highlights
+Before submitting a Pull Request (PR), please ensure:
+- 📌 **Discuss new features**: Start with an [Issue](https://github.com/smart-doc-group/smart-doc/issues) to align on proposed changes.
+- 🧩 **Single-focused PRs**: Submit one fix or feature per PR to simplify reviews.
+- 🌍 **English comments**: Use English for code comments to support international collaboration.
+- ✅ **Code quality**: Follow the [Spring Java Format](https://github.com/spring-io/java-format) style and add unit tests.
+- 📄 **Update documentation**: Reflect your changes in relevant documentation [`smart-doc-group.github.io`](https://github.com/smart-doc-group/smart-doc-group.github.io/tree/master/docs). if needed.
+
+## Documentation and Examples
+If your contribution involves:
+- 🛠️ **Configuration changes**:
+	- Check if your PR adds or modifies configurations (e.g., new parameters, default value updates).
+	- Update or add corresponding documentation in the [`smart-doc-group.github.io`](https://github.com/smart-doc-group/smart-doc-group.github.io/tree/master/docs).
+- 📚 **New features**:
+	- Provide usage examples in the [`smart-doc-example-cn`](https://github.com/smart-doc-group/smart-doc-example-cn) repository to demonstrate implementation.
+
+
+## How to Contribute
+1. Fork the repository and clone it locally.
+2. Create a new branch for your changes.
+3. Test your modifications using `smart-doc` (see [Quick Start](https://smart-doc-group.github.io/guide/getting-started)).
+4. Format code with `mvn spring-javaformat:apply`.
+5. Submit a PR to the main repository.
+
+## Community Engagement
+- 📰 Share your use cases or articles in the [Discussions](https://github.com/smart-doc-group/smart-doc/discussions) section.
+- ❓ Help answer questions in the `Help` category.
+- 💡 Propose ideas or showcase tools in `Ideas` or `Show and tell`.
+
+Your contributions are vital to making `smart-doc` better for everyone. Thank you!  

CONTRIBUTING_CN.md

@@ -0,0 +1,33 @@
+# 贡献指南
+
+感谢您对参与 `smart-doc` 贡献的兴趣！详细的贡献指引请参考我们的官方 [**贡献指南文档**](https://smart-doc-group.github.io/zh/guide/community/contributing)。
+
+## 核心要求
+提交 Pull Request (PR) 前请确保：
+- 📌 **新功能需先讨论**：通过 [Issue](https://github.com/smart-doc-group/smart-doc/issues) 与社区对齐需求，避免重复劳动。
+- 🧩 **单焦点 PR**：每次提交仅包含一个修复或功能，简化代码审查。
+- 🌍 **英文注释**：代码注释使用英文，支持国际化协作。
+- ✅ **代码质量**：遵循 [Spring Java Format](https://github.com/spring-io/java-format) 风格，添加单元测试。
+- 📄 **文档同步更新**：若涉及功能变更，请同步更新 [`smart-doc-group.github.io`](https://github.com/smart-doc-group/smart-doc-group.github.io/tree/master/docs) 文档。
+
+## 文档与示例要求
+若贡献包含以下内容：
+- 🛠️ **配置项变更**：
+	- 检查 PR 是否新增/修改配置（如新增参数、修改默认值）。
+	- 在 [`smart-doc-group.github.io`](https://github.com/smart-doc-group/smart-doc-group.github.io/tree/master/docs) 中补充或更新对应文档。
+- 📚 **新功能实现**：
+	- 在 [`smart-doc-example-cn`](https://github.com/smart-doc-group/smart-doc-example-cn) 仓库提供使用示例，便于其他用户快速理解。
+
+## 贡献步骤
+1. Fork 仓库并本地克隆。
+2. 创建新分支进行修改。
+3. 使用 `smart-doc` 测试改动（参考 [快速入门](https://smart-doc-group.github.io/zh/guide/getting-started)）。
+4. 执行 `mvn spring-javaformat:apply` 格式化代码。
+5. 向主仓库提交 PR。
+
+## 社区互动
+- 📰 在 [Discussions](https://github.com/smart-doc-group/smart-doc/discussions) 分享使用案例或技术文章。
+- ❓ 在 `Help` 分类帮助解答用户疑问。
+- 💡 在 `Ideas` 或 `Show and tell` 提出建议或展示相关工具。
+
+您的贡献将帮助 `smart-doc` 更好地服务全球开发者！感谢支持！

pom.xml

@@ -5,7 +5,7 @@
     <modelVersion>4.0.0</modelVersion>
     <artifactId>smart-doc</artifactId>
     <packaging>jar</packaging>
-    <version>3.0.9</version>
+    <version>3.1.0</version>
 
     <name>smart-doc</name>
     <url>https://github.com/TongchengOpenSource/smart-doc.git</url>
@@ -36,14 +36,14 @@
     <properties>
         <java.version>1.8</java.version>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <junit.jupiter.version>5.12.0</junit.jupiter.version>
-        <beetl.version>3.19.0.RELEASE</beetl.version>
+        <junit.jupiter.version>5.12.2</junit.jupiter.version>
+        <beetl.version>3.19.1.RELEASE</beetl.version>
         <common-util.version>2.2.8</common-util.version>
         <qdox.version>2.0.3.5</qdox.version>
         <datafaker.version>1.4.0</datafaker.version>
-        <gson.version>2.12.1</gson.version>
+        <gson.version>2.13.1</gson.version>
         <eclipse.jgit.version>5.13.3.202401111512-r</eclipse.jgit.version>
-        <slf4j-api.version>2.0.16</slf4j-api.version>
+        <slf4j-api.version>2.0.17</slf4j-api.version>
 
         <!-- plugin version -->
         <maven-compiler-plugin.version>3.14.0</maven-compiler-plugin.version>

src/main/java/com/ly/doc/builder/openapi/AbstractOpenApiBuilder.java

@@ -155,6 +155,9 @@ public Map<String, Object> buildPaths(ApiConfig apiConfig, ApiSchema<ApiDoc> api
 				String[] paths = methodDoc.getPath().split(";");
 				for (String path : paths) {
 					path = path.trim();
+					if (StringUtil.isNotEmpty(apiConfig.getPathPrefix())) {
+						path = path.replace(apiConfig.getPathPrefix(), "");
+					}
 					Map<String, Object> request = this.buildPathUrls(apiConfig, methodDoc, methodDoc.getClazzDoc(),
 							apiSchema.getApiExceptionStatuses());
 					if (!pathMap.containsKey(path)) {
@@ -471,6 +474,7 @@ public Map<String, Object> buildProperties(List<ApiParam> apiParam, Map<String,
 				propertiesData.put(field, this.buildPropertiesData(param, component, isResp));
 			}
 			if (!propertiesData.isEmpty()) {
+				properties.put("type", "object");
 				properties.put("properties", propertiesData);
 			}
 			if (!CollectionUtil.isEmpty(requiredList)) {
@@ -617,4 +621,4 @@ public ApiSchema<ApiDoc> getOpenApiDocs(ApiConfig config, JavaProjectBuilder pro
 		return docBuildTemplate.getApiData(configBuilder);
 	}
 
-}
+}

src/main/java/com/ly/doc/builder/openapi/OpenApiBuilder.java

@@ -36,7 +36,6 @@
 import org.apache.commons.lang3.StringUtils;
 
 import java.util.*;
-import java.util.stream.Collectors;
 
 /**
  *
@@ -52,6 +51,11 @@ public class OpenApiBuilder extends AbstractOpenApiBuilder {
 	 */
 	private static final OpenApiBuilder INSTANCE = new OpenApiBuilder();
 
+	/**
+	 * OperationId OrderNo Map
+	 */
+	private static final Map<String, Integer> OPERATIONID_ORDER_NO_MAP = new HashMap<>();
+
 	/**
 	 * private constructor
 	 */
@@ -148,8 +152,19 @@ public Map<String, Object> buildPathUrlsRequest(ApiConfig apiConfig, ApiMethodDo
 		request.put("deprecated", apiMethodDoc.isDeprecated());
 		List<String> paths = OpenApiSchemaUtil.getPatternResult("[A-Za-z0-9_{}]*", apiMethodDoc.getPath());
 		paths.add(apiMethodDoc.getType());
-		String operationId = paths.stream().filter(StringUtils::isNotEmpty).collect(Collectors.joining("-"));
-		request.put("operationId", operationId);
+
+		// add operationId
+		String methodName = apiMethodDoc.getMethodName();
+		if (OPERATIONID_ORDER_NO_MAP.containsKey(methodName)) {
+			int order = OPERATIONID_ORDER_NO_MAP.get(methodName);
+			request.put("operationId", methodName + "_" + order);
+			OPERATIONID_ORDER_NO_MAP.put(methodName, order + 1);
+		}
+		else {
+			request.put("operationId", methodName);
+			OPERATIONID_ORDER_NO_MAP.put(methodName, 1);
+		}
+
 		// add extension attribution
 		if (apiMethodDoc.getExtensions() != null) {
 			apiMethodDoc.getExtensions().forEach((key, value) -> request.put("x-" + key, value));

src/main/java/com/ly/doc/constants/DocValidatorAnnotationEnum.java

@@ -18,17 +18,24 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+
 package com.ly.doc.constants;
 
+import java.util.Collections;
+import java.util.HashMap;
 import java.util.HashSet;
+import java.util.Map;
 import java.util.Set;
 
 /**
- * spring validator annotations
+ * Enumeration of Spring validator annotations with metadata for documentation generation.
+ * <p>
+ * This enum maps validation annotations to their default attribute values, enabling
+ * automatic replacement of placeholders in validation messages (e.g., {min}, {max}).
  *
  * @author yu 2019/9/19.
  */
-public enum DocValidatorAnnotationEnum {
+public enum DocValidatorAnnotationEnum implements ValidationAnnotationDefaultsProvider {
 
 	/**
 	 * Spring validator annotations `@NotEmpty`
@@ -83,7 +90,15 @@ public enum DocValidatorAnnotationEnum {
 	/**
 	 * Spring validator annotations `@Size`
 	 */
-	SIZE(JSRAnnotationConstants.SIZE),
+	SIZE(JSRAnnotationConstants.SIZE) {
+		public Map<String, String> getDefaultProperties() {
+			// @Size default values (min=0, max=Integer.MAX_VALUE)
+			Map<String, String> sizeDefaults = new HashMap<>(2);
+			sizeDefaults.put("min", "0");
+			sizeDefaults.put("max", Integer.toString(Integer.MAX_VALUE));
+			return sizeDefaults;
+		}
+	},
 
 	/**
 	 * Spring validator annotations `@Digits`
@@ -143,17 +158,34 @@ public enum DocValidatorAnnotationEnum {
 	/**
 	 * Spring validator annotations `@Length`
 	 */
-	LENGTH(JSRAnnotationConstants.LENGTH),
+	LENGTH(JSRAnnotationConstants.LENGTH) {
+		public Map<String, String> getDefaultProperties() {
+			// @Length default values (min=0, max=Integer.MAX_VALUE)
+			Map<String, String> lengthDefaults = new HashMap<>(2);
+			lengthDefaults.put("min", "0");
+			lengthDefaults.put("max", Integer.toString(Integer.MAX_VALUE));
+			return lengthDefaults;
+		}
+	},
 
 	/**
 	 * Spring validator annotations `@Range`
 	 */
-	RANGE(JSRAnnotationConstants.RANGE),
+	RANGE(JSRAnnotationConstants.RANGE) {
+		@Override
+		public Map<String, String> getDefaultProperties() {
+			// @Range default values (min=0, max=Long.MAX_VALUE)
+			Map<String, String> rangeDefaults = new HashMap<>(2);
+			rangeDefaults.put("min", "0");
+			rangeDefaults.put("max", Long.toString(Long.MAX_VALUE));
+			return rangeDefaults;
+		}
+	},
 
 	/**
 	 * Spring validator annotations `@Validated`
 	 */
-	VALIDATED(JSRAnnotationConstants.VALIDATED);
+	VALIDATED(JSRAnnotationConstants.VALIDATED),;
 
 	/**
 	 * annotation value
@@ -186,4 +218,30 @@ public enum DocValidatorAnnotationEnum {
 		EXCLUDED_ANNOTATIONS.add(VALIDATED.value);
 	}
 
+	/**
+	 * Looks up and returns the default attribute values for a validation annotation.
+	 * <p>
+	 * This method iterates through all {@link DocValidatorAnnotationEnum} entries to find
+	 * the matching annotation definition. If found, returns the associated default values
+	 * from {@link ValidationAnnotationDefaultsProvider#getDefaultProperties()}.
+	 * @param annotationName Fully qualified class name of the annotation (e.g.,
+	 * "javax.validation.constraints.Min")
+	 * @return An unmodifiable map of default attribute name-value pairs. Returns an empty
+	 * map if:
+	 * <ul>
+	 * <li>No matching annotation is found</li>
+	 * <li>The annotation does not define default values</li>
+	 * </ul>
+	 * @see DocValidatorAnnotationEnum
+	 * @see ValidationAnnotationDefaultsProvider
+	 */
+	public static Map<String, String> getDefaults(String annotationName) {
+		for (DocValidatorAnnotationEnum entry : values()) {
+			if (entry.value.equals(annotationName)) {
+				return entry.getDefaultProperties();
+			}
+		}
+		return Collections.emptyMap();
+	}
+
 }

src/main/java/com/ly/doc/constants/ValidationAnnotationDefaultsProvider.java

@@ -0,0 +1,59 @@
+/*
+ * smart-doc
+ *
+ * Copyright (C) 2018-2025 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.constants;
+
+import java.util.Collections;
+import java.util.Map;
+
+/**
+ * Provides default attribute values for validation annotations.
+ * <p>
+ * Implementations of this interface should return immutable maps containing the default
+ * values for validation annotation attributes. These defaults are used for placeholder
+ * resolution in validation messages (e.g., replacing {min} with the actual default value
+ * from the annotation).
+ */
+public interface ValidationAnnotationDefaultsProvider {
+
+	/**
+	 * Gets the default attribute values for the associated validation annotation.
+	 * <p>
+	 * The returned map should be immutable and contain only primitive/wrapper values
+	 * converted to their String representations. Implementations should return an empty
+	 * map if no defaults are available.
+	 * @return Unmodifiable map of default attribute values, or empty map if none exist
+	 */
+	default Map<String, String> getDefaultProperties() {
+		return Collections.emptyMap();
+	}
+
+	/**
+	 * Checks if the annotation has any default property values defined.
+	 * @return true if default properties are available, false otherwise
+	 */
+	default boolean hasDefaults() {
+		return !this.getDefaultProperties().isEmpty();
+	}
+
+}

src/main/java/com/ly/doc/function/HtmlEscape.java

@@ -25,19 +25,47 @@
 import org.beetl.core.Context;
 import org.beetl.core.Function;
 
+import java.util.HashMap;
+import java.util.Map;
+
 /**
- * beetl template function
+ * Function to escape HTML content in Beetl templates.
+ * <p>
+ * This class provides a method to replace specific HTML characters with their
+ * corresponding escape sequences and clean up comments.
+ * <p>
+ * For example, it replaces:
+ * <p>
+ * - <code>"</code> with <code>&amp;quot;</code>
  *
- * @author yu 2021/6/26.
+ * @author yu
+ * @since 2021/6/26
  */
 public class HtmlEscape implements Function {
 
+	/**
+	 * Map to hold HTML escape sequences.
+	 */
+	private static final Map<String, String> HTML_ESCAPE_MAP;
+
+	static {
+		HTML_ESCAPE_MAP = new HashMap<>();
+		HTML_ESCAPE_MAP.put("<p>", "");
+		HTML_ESCAPE_MAP.put("</p>", " ");
+	}
+
 	@Override
-	public String call(Object[] paras, Context ctx) {
-		String str = String.valueOf(paras[0]).replaceAll("&", "&amp;");
-		str = str.replaceAll("\"", "&quot;");
-		str = str.replaceAll("<p>", "").replaceAll("</p>", " ");
-		return DocUtil.replaceNewLineToHtmlBr(DocUtil.getEscapeAndCleanComment(str));
+	public String call(Object[] params, Context ctx) {
+		if (params == null || params.length == 0 || params[0] == null) {
+			return "";
+		}
+		String html = String.valueOf(params[0]);
+		for (Map.Entry<String, String> entry : HTML_ESCAPE_MAP.entrySet()) {
+			html = html.replace(entry.getKey(), entry.getValue());
+		}
+
+		html = DocUtil.getEscapeAndCleanComment(html);
+		return DocUtil.replaceNewLineToHtmlBr(html);
 	}
 
 }