From 08abe94c85f098c3a797fa5b3255136654dc2720 Mon Sep 17 00:00:00 2001 From: Charles7c Date: Sat, 14 Jun 2025 22:16:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(api-doc):=20ApiDocUtils=20=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=20buildGroupedOpenApi=EF=BC=88=E6=9E=84=E5=BB=BA?= =?UTF-8?q?=E5=88=86=E7=BB=84=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3=EF=BC=89?= =?UTF-8?q?=20=E6=96=B9=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DocUtils => ApiDocUtils --- .../handler/BaseEnumParameterHandler.java | 8 ++--- .../util/{DocUtils.java => ApiDocUtils.java} | 31 +++++++++++++++++-- .../response/ApiDocGlobalResponseHandler.java | 4 +-- 3 files changed, 35 insertions(+), 8 deletions(-) rename continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/util/{DocUtils.java => ApiDocUtils.java} (80%) diff --git a/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/handler/BaseEnumParameterHandler.java b/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/handler/BaseEnumParameterHandler.java index b13462ee..1a6d6b63 100644 --- a/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/handler/BaseEnumParameterHandler.java +++ b/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/handler/BaseEnumParameterHandler.java @@ -26,7 +26,7 @@ import io.swagger.v3.oas.models.parameters.Parameter; import org.springdoc.core.customizers.ParameterCustomizer; import org.springdoc.core.customizers.PropertyCustomizer; import org.springframework.core.MethodParameter; -import top.continew.starter.apidoc.util.DocUtils; +import top.continew.starter.apidoc.util.ApiDocUtils; import top.continew.starter.core.enums.BaseEnum; import java.lang.reflect.Type; @@ -84,9 +84,9 @@ public class BaseEnumParameterHandler implements ParameterCustomizer, PropertyCu BaseEnum[] enums = (BaseEnum[])enumClass.getEnumConstants(); List valueList = Arrays.stream(enums).map(e -> e.getValue().toString()).toList(); schema.setEnum(valueList); - String enumValueType = DocUtils.getEnumValueTypeAsString(enumClass); + String enumValueType = ApiDocUtils.getEnumValueTypeAsString(enumClass); schema.setType(enumValueType); - schema.setFormat(DocUtils.resolveFormat(enumValueType)); + schema.setFormat(ApiDocUtils.resolveFormat(enumValueType)); } /** @@ -97,7 +97,7 @@ public class BaseEnumParameterHandler implements ParameterCustomizer, PropertyCu * @return 追加后的描述字符串 */ private String appendEnumDescription(String originalDescription, Class enumClass) { - return originalDescription + "" + DocUtils.getDescMap(enumClass) + ""; + return originalDescription + "" + ApiDocUtils.getDescMap(enumClass) + ""; } /** diff --git a/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/util/DocUtils.java b/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/util/ApiDocUtils.java similarity index 80% rename from continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/util/DocUtils.java rename to continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/util/ApiDocUtils.java index 7164ed8f..d7340577 100644 --- a/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/util/DocUtils.java +++ b/continew-starter-api-doc/src/main/java/top/continew/starter/apidoc/util/ApiDocUtils.java @@ -16,6 +16,7 @@ package top.continew.starter.apidoc.util; +import org.springdoc.core.models.GroupedOpenApi; import org.springframework.web.bind.annotation.RestController; import top.continew.starter.core.enums.BaseEnum; @@ -30,11 +31,37 @@ import java.util.stream.Collectors; * 接口文档工具类 * * @author echo + * @author Charles7c * @since 2.5.2 */ -public class DocUtils { +public class ApiDocUtils { - private DocUtils() { + private ApiDocUtils() { + } + + /** + * 构建分组接口文档 + * + * @param group 分组名称 + * @param pathsToMatch 路径匹配 + * @return GroupedOpenApi + * @since 2.13.0 + */ + public static GroupedOpenApi buildGroupedOpenApi(String group, String... pathsToMatch) { + return buildGroupedOpenApi(group, group, pathsToMatch); + } + + /** + * 构建分组接口文档 + * + * @param group 分组名称 + * @param displayName 分组显示名称 + * @param pathsToMatch 路径匹配 + * @return GroupedOpenApi + * @since 2.13.0 + */ + public static GroupedOpenApi buildGroupedOpenApi(String group, String displayName, String... pathsToMatch) { + return GroupedOpenApi.builder().group(group).displayName(displayName).pathsToMatch(pathsToMatch).build(); } /** diff --git a/continew-starter-web/src/main/java/top/continew/starter/web/autoconfigure/response/ApiDocGlobalResponseHandler.java b/continew-starter-web/src/main/java/top/continew/starter/web/autoconfigure/response/ApiDocGlobalResponseHandler.java index 25736af7..fd0c2f16 100644 --- a/continew-starter-web/src/main/java/top/continew/starter/web/autoconfigure/response/ApiDocGlobalResponseHandler.java +++ b/continew-starter-web/src/main/java/top/continew/starter/web/autoconfigure/response/ApiDocGlobalResponseHandler.java @@ -20,7 +20,7 @@ import cn.hutool.core.util.ClassUtil; import org.apache.commons.lang3.reflect.TypeUtils; import org.springdoc.core.parsers.ReturnTypeParser; import org.springframework.core.MethodParameter; -import top.continew.starter.apidoc.util.DocUtils; +import top.continew.starter.apidoc.util.ApiDocUtils; import java.lang.reflect.Type; @@ -54,7 +54,7 @@ public class ApiDocGlobalResponseHandler implements ReturnTypeParser { // 获取返回类型 Type returnType = ReturnTypeParser.super.getReturnType(methodParameter); // 判断是否具有 RestController 注解 - if (!DocUtils.hasRestControllerAnnotation(methodParameter.getContainingClass())) { + if (!ApiDocUtils.hasRestControllerAnnotation(methodParameter.getContainingClass())) { return returnType; } // 如果为响应类型，则直接返回