diff --git a/build.gradle b/build.gradle index 9fae654..dbf253c 100644 --- a/build.gradle +++ b/build.gradle @@ -4,7 +4,7 @@ plugins { } //버전 변경은 여기서 -def commonVer = "beta.1.1.05" +def commonVer = "beta.1.1.13" group = 'com.kri.common' version = commonVer diff --git a/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java b/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java index 1370fc2..4de6159 100644 --- a/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java +++ b/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java @@ -1,13 +1,23 @@ package com.kri.common.autoconfigure.swagger; import com.kri.common.autoconfigure.auth.apikey.ApiKeyProperties; +import com.kri.common.runtime.swagger.CodeEnumOpenApiCustomizer; +import com.kri.common.runtime.swagger.CodeEnumModelConverter; +import com.kri.common.runtime.swagger.CodeEnumSwaggerSupport; import com.kri.common.runtime.swagger.SwaggerIpFilter; +import io.swagger.v3.core.converter.AnnotatedType; +import io.swagger.v3.core.converter.ModelConverter; import io.swagger.v3.oas.models.Components; import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; +import io.swagger.v3.oas.models.media.Schema; +import io.swagger.v3.oas.models.parameters.Parameter; import io.swagger.v3.oas.models.security.SecurityRequirement; import io.swagger.v3.oas.models.security.SecurityScheme; import lombok.RequiredArgsConstructor; +import org.springdoc.core.customizers.GlobalOpenApiCustomizer; +import org.springdoc.core.customizers.ParameterCustomizer; +import org.springdoc.core.customizers.PropertyCustomizer; import org.springdoc.core.models.GroupedOpenApi; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; @@ -16,8 +26,9 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.boot.web.servlet.FilterRegistrationBean; import org.springframework.context.annotation.Bean; +import org.springframework.core.MethodParameter; -@AutoConfiguration +@AutoConfiguration(beforeName = "org.springdoc.core.configuration.SpringDocConfiguration") @EnableConfigurationProperties(KriSwaggerProperties.class) @ConditionalOnClass({OpenAPI.class, GroupedOpenApi.class}) @ConditionalOnProperty(prefix = "kri.swagger", name = "enabled", havingValue = "true", matchIfMissing = true) @@ -72,6 +83,42 @@ public class KriSwaggerAutoConfiguration { return builder.build(); } + @Bean + @ConditionalOnMissingBean(name = "codeEnumModelConverter") + public ModelConverter codeEnumModelConverter() { + return new CodeEnumModelConverter(); + } + + @Bean + @ConditionalOnMissingBean(name = "codeEnumPropertyCustomizer") + public PropertyCustomizer codeEnumPropertyCustomizer() { + return (Schema property, AnnotatedType type) -> { + CodeEnumSwaggerSupport.resolveCodeEnumClass(type) + .ifPresent(enumClass -> CodeEnumSwaggerSupport.applyEnumMetadata(property, enumClass)); + return property; + }; + } + + @Bean + @ConditionalOnMissingBean(name = "codeEnumParameterCustomizer") + public ParameterCustomizer codeEnumParameterCustomizer() { + return (Parameter parameterModel, MethodParameter methodParameter) -> { + CodeEnumSwaggerSupport.resolveCodeEnumClass(methodParameter.getParameterType()) + .ifPresent(enumClass -> { + CodeEnumSwaggerSupport.applyEnumMetadata(parameterModel.getSchema(), enumClass); + parameterModel.description( + CodeEnumSwaggerSupport.mergeEnumDescription(parameterModel.getDescription(), enumClass)); + }); + return parameterModel; + }; + } + + @Bean + @ConditionalOnMissingBean(name = "codeEnumOpenApiCustomizer") + public GlobalOpenApiCustomizer codeEnumOpenApiCustomizer() { + return new CodeEnumOpenApiCustomizer(properties.getBasePackage()); + } + @Bean @ConditionalOnMissingBean(name = "swaggerIpFilter") public FilterRegistrationBean swaggerIpFilter() { diff --git a/src/main/java/com/kri/common/runtime/swagger/CodeEnumModelConverter.java b/src/main/java/com/kri/common/runtime/swagger/CodeEnumModelConverter.java new file mode 100644 index 0000000..d1064d3 --- /dev/null +++ b/src/main/java/com/kri/common/runtime/swagger/CodeEnumModelConverter.java @@ -0,0 +1,22 @@ +package com.kri.common.runtime.swagger; + +import io.swagger.v3.core.converter.AnnotatedType; +import io.swagger.v3.core.converter.ModelConverter; +import io.swagger.v3.core.converter.ModelConverterContext; +import io.swagger.v3.oas.models.media.Schema; +import java.util.Iterator; + +public class CodeEnumModelConverter implements ModelConverter { + + @Override + public Schema resolve(AnnotatedType type, ModelConverterContext context, Iterator chain) { + if (!chain.hasNext()) { + return null; + } + + Schema resolvedSchema = chain.next().resolve(type, context, chain); + CodeEnumSwaggerSupport.resolveCodeEnumClass(type) + .ifPresent(enumClass -> CodeEnumSwaggerSupport.applyEnumMetadata(resolvedSchema, enumClass)); + return resolvedSchema; + } +} diff --git a/src/main/java/com/kri/common/runtime/swagger/CodeEnumOpenApiCustomizer.java b/src/main/java/com/kri/common/runtime/swagger/CodeEnumOpenApiCustomizer.java new file mode 100644 index 0000000..71bef99 --- /dev/null +++ b/src/main/java/com/kri/common/runtime/swagger/CodeEnumOpenApiCustomizer.java @@ -0,0 +1,209 @@ +package com.kri.common.runtime.swagger; + +import io.swagger.v3.oas.models.OpenAPI; +import io.swagger.v3.oas.models.PathItem; +import io.swagger.v3.oas.models.media.ArraySchema; +import io.swagger.v3.oas.models.media.Content; +import io.swagger.v3.oas.models.media.MediaType; +import io.swagger.v3.oas.models.media.Schema; +import io.swagger.v3.oas.models.parameters.Parameter; +import io.swagger.v3.oas.models.responses.ApiResponse; +import java.lang.reflect.Field; +import java.util.LinkedHashMap; +import java.util.Map; +import org.springdoc.core.customizers.GlobalOpenApiCustomizer; +import org.springframework.core.type.classreading.MetadataReader; +import org.springframework.core.type.classreading.MetadataReaderFactory; +import org.springframework.core.type.filter.TypeFilter; +import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider; + +public class CodeEnumOpenApiCustomizer implements GlobalOpenApiCustomizer { + + private final String basePackage; + private Map> componentClasses; + + public CodeEnumOpenApiCustomizer(String basePackage) { + this.basePackage = basePackage; + } + + @Override + public void customise(OpenAPI openApi) { + if (openApi == null) { + return; + } + + Map schemas = openApi.getComponents() != null + ? openApi.getComponents().getSchemas() + : null; + Map> componentEnumClasses = CodeEnumSwaggerSupport.collectComponentEnumClasses(schemas); + Map> componentDtoClasses = collectComponentClasses(schemas); + + if (schemas != null) { + for (Map.Entry entry : schemas.entrySet()) { + Schema schema = entry.getValue(); + Class componentClass = componentDtoClasses.get(entry.getKey()); + if (componentClass != null) { + applyToComponentProperties(schema, componentClass); + } + CodeEnumSwaggerSupport.reapplyEnumMetadata(schema); + applyToNestedSchemas(schema, componentEnumClasses); + } + } + + if (openApi.getPaths() == null) { + return; + } + + for (PathItem pathItem : openApi.getPaths().values()) { + if (pathItem == null || pathItem.readOperations() == null) { + continue; + } + + pathItem.readOperations().forEach(operation -> { + if (operation.getParameters() != null) { + for (Parameter parameter : operation.getParameters()) { + applyToSchema(parameter.getSchema(), componentEnumClasses); + parameter.description( + CodeEnumSwaggerSupport.mergeEnumDescription(parameter.getDescription(), parameter.getSchema())); + applyToContent(parameter.getContent(), componentEnumClasses); + } + } + + if (operation.getRequestBody() != null) { + applyToContent(operation.getRequestBody().getContent(), componentEnumClasses); + } + + if (operation.getResponses() != null) { + for (ApiResponse response : operation.getResponses().values()) { + applyToContent(response.getContent(), componentEnumClasses); + } + } + }); + } + } + + private void applyToContent(Content content, Map> componentEnumClasses) { + if (content == null) { + return; + } + + for (MediaType mediaType : content.values()) { + if (mediaType != null) { + applyToSchema(mediaType.getSchema(), componentEnumClasses); + } + } + } + + private void applyToSchema(Schema schema, Map> componentEnumClasses) { + if (schema == null) { + return; + } + + if (schema.get$ref() != null) { + Class enumClass = componentEnumClasses.get(extractComponentName(schema.get$ref())); + if (enumClass != null) { + CodeEnumSwaggerSupport.applyEnumMetadata(schema, enumClass); + } + return; + } + + CodeEnumSwaggerSupport.reapplyEnumMetadata(schema); + applyToNestedSchemas(schema, componentEnumClasses); + } + + private void applyToNestedSchemas(Schema schema, Map> componentEnumClasses) { + if (schema == null) { + return; + } + + if (schema instanceof ArraySchema arraySchema) { + applyToSchema(arraySchema.getItems(), componentEnumClasses); + } + + if (schema.getProperties() != null) { + Map properties = new LinkedHashMap<>(schema.getProperties()); + for (Schema propertySchema : properties.values()) { + applyToSchema(propertySchema, componentEnumClasses); + } + } + + applyToSchema(schema.getAdditionalProperties() instanceof Schema additionalSchema ? additionalSchema : null, + componentEnumClasses); + } + + private String extractComponentName(String ref) { + int lastSlashIndex = ref.lastIndexOf('/'); + return lastSlashIndex >= 0 ? ref.substring(lastSlashIndex + 1) : ref; + } + + private void applyToComponentProperties(Schema schema, Class componentClass) { + if (schema == null || schema.getProperties() == null) { + return; + } + + for (Object entry : schema.getProperties().entrySet()) { + if (!(entry instanceof Map.Entry propertyEntry) + || !(propertyEntry.getKey() instanceof String propertyName) + || !(propertyEntry.getValue() instanceof Schema propertySchema)) { + continue; + } + + findField(componentClass, propertyName).ifPresent(field -> { + CodeEnumSwaggerSupport.applyEnumMetadata(propertySchema, field.getGenericType()); + CodeEnumSwaggerSupport.applyContainerEnumMetadata(propertySchema, field.getGenericType()); + }); + } + } + + private java.util.Optional findField(Class componentClass, String fieldName) { + Class currentClass = componentClass; + while (currentClass != null && currentClass != Object.class) { + try { + Field field = currentClass.getDeclaredField(fieldName); + return java.util.Optional.of(field); + } catch (NoSuchFieldException ignored) { + currentClass = currentClass.getSuperclass(); + } + } + return java.util.Optional.empty(); + } + + private Map> collectComponentClasses(Map schemas) { + if (schemas == null || schemas.isEmpty() || basePackage == null || basePackage.isBlank()) { + return Map.of(); + } + + if (componentClasses != null) { + return componentClasses; + } + + Map> classes = new LinkedHashMap<>(); + ClassPathScanningCandidateComponentProvider scanner = + new ClassPathScanningCandidateComponentProvider(false); + scanner.addIncludeFilter(new AllClassesTypeFilter()); + + for (var beanDefinition : scanner.findCandidateComponents(basePackage)) { + String className = beanDefinition.getBeanClassName(); + if (className == null || className.isBlank()) { + continue; + } + + try { + Class clazz = Class.forName(className); + classes.putIfAbsent(clazz.getSimpleName(), clazz); + } catch (ClassNotFoundException ignored) { + } + } + + componentClasses = classes; + return componentClasses; + } + + private static class AllClassesTypeFilter implements TypeFilter { + + @Override + public boolean match(MetadataReader metadataReader, MetadataReaderFactory metadataReaderFactory) { + return true; + } + } +} diff --git a/src/main/java/com/kri/common/runtime/swagger/CodeEnumSwaggerSupport.java b/src/main/java/com/kri/common/runtime/swagger/CodeEnumSwaggerSupport.java new file mode 100644 index 0000000..6e204ec --- /dev/null +++ b/src/main/java/com/kri/common/runtime/swagger/CodeEnumSwaggerSupport.java @@ -0,0 +1,299 @@ +package com.kri.common.runtime.swagger; + +import com.kri.common.feature.enums.CodeEnum; +import io.swagger.v3.core.converter.AnnotatedType; +import io.swagger.v3.oas.models.media.ArraySchema; +import io.swagger.v3.oas.models.media.Schema; +import java.lang.reflect.ParameterizedType; +import java.lang.reflect.Type; +import java.util.Arrays; +import java.util.Collection; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.StringJoiner; + +public final class CodeEnumSwaggerSupport { + + private static final String ENUM_VALUES_PREFIX = "Enum values: "; + private static final String ENUM_DESCRIPTION_EXTENSION = "x-kri-code-enum-description"; + private static final String ENUM_CLASS_EXTENSION = "x-kri-code-enum-class"; + private static final String ENUM_VARNAMES_EXTENSION = "x-enum-varnames"; + private static final String ENUM_DESCRIPTIONS_EXTENSION = "x-enum-descriptions"; + + private CodeEnumSwaggerSupport() { + } + + public static Optional> resolveCodeEnumClass(AnnotatedType annotatedType) { + if (annotatedType == null) { + return Optional.empty(); + } + + return resolveCodeEnumClass(annotatedType.getType()); + } + + public static Optional> resolveCodeEnumClass(Type type) { + if (type instanceof Class clazz) { + return isCodeEnumClass(clazz) ? Optional.of(clazz) : Optional.empty(); + } + + if (type instanceof ParameterizedType parameterizedType) { + return resolveCodeEnumClass(parameterizedType.getRawType()); + } + + return Optional.empty(); + } + + public static Optional> resolveCodeEnumClass(Class clazz) { + if (clazz == null) { + return Optional.empty(); + } + + return isCodeEnumClass(clazz) ? Optional.of(clazz) : Optional.empty(); + } + + public static void applyEnumMetadata(Schema schema, Type type) { + resolveCodeEnumClass(type).ifPresent(enumClass -> applyEnumMetadata(schema, enumClass)); + } + + public static void applyContainerEnumMetadata(Schema schema, Type type) { + if (schema == null || type == null) { + return; + } + + if (type instanceof Class clazz && clazz.isArray()) { + if (schema instanceof ArraySchema arraySchema) { + applyEnumMetadata(arraySchema.getItems(), clazz.getComponentType()); + } + return; + } + + if (!(type instanceof ParameterizedType parameterizedType)) { + return; + } + + Type rawType = parameterizedType.getRawType(); + if (!(rawType instanceof Class rawClass)) { + return; + } + + Type[] actualTypes = parameterizedType.getActualTypeArguments(); + if (Collection.class.isAssignableFrom(rawClass) && actualTypes.length == 1) { + if (schema instanceof ArraySchema arraySchema) { + applyEnumMetadata(arraySchema.getItems(), actualTypes[0]); + } + return; + } + + if (Map.class.isAssignableFrom(rawClass) && actualTypes.length == 2) { + Object additionalProperties = schema.getAdditionalProperties(); + if (additionalProperties instanceof Schema additionalPropertiesSchema) { + applyEnumMetadata(additionalPropertiesSchema, actualTypes[1]); + } + } + } + + public static void applyEnumMetadata(Schema schema, Class enumClass) { + if (schema == null) { + return; + } + + Optional enumDescription = buildEnumDescription(enumClass); + if (enumDescription.isEmpty()) { + return; + } + + String description = enumDescription.get(); + Object example = firstCodeValue(enumClass); + applyCodeType(schema, example); + schema.description(mergeDescription(schema.getDescription(), description)); + schema.addExtension(ENUM_DESCRIPTION_EXTENSION, description); + schema.addExtension(ENUM_CLASS_EXTENSION, enumClass.getName()); + schema.addExtension(ENUM_VARNAMES_EXTENSION, enumNames(enumClass)); + schema.addExtension(ENUM_DESCRIPTIONS_EXTENSION, enumDescriptions(enumClass)); + if (schema.getEnum() == null || schema.getEnum().isEmpty()) { + applyEnumCodes(schema, enumClass); + } + + if (example != null && schema.getExample() == null) { + schema.example(example); + } + } + + public static void reapplyEnumMetadata(Schema schema) { + if (schema == null) { + return; + } + + Map extensions = schema.getExtensions(); + if (extensions == null) { + return; + } + + Object description = extensions.get(ENUM_DESCRIPTION_EXTENSION); + if (description instanceof String enumDescription && !enumDescription.isBlank()) { + schema.description(mergeDescription(schema.getDescription(), enumDescription)); + } + } + + public static String mergeEnumDescription(String original, Class enumClass) { + return buildEnumDescription(enumClass) + .map(enumDescription -> mergeDescription(original, enumDescription)) + .orElse(original); + } + + public static String mergeEnumDescription(String original, Schema schema) { + Optional enumDescription = getEnumDescription(schema); + return enumDescription + .map(description -> mergeDescription(original, description)) + .orElse(original); + } + + public static Optional getEnumDescription(Schema schema) { + if (schema == null || schema.getExtensions() == null) { + return Optional.empty(); + } + + Object description = schema.getExtensions().get(ENUM_DESCRIPTION_EXTENSION); + if (description instanceof String enumDescription && !enumDescription.isBlank()) { + return Optional.of(enumDescription); + } + + return Optional.empty(); + } + + public static Optional buildEnumDescription(Class enumClass) { + if (!isCodeEnumClass(enumClass)) { + return Optional.empty(); + } + + Object[] constants = enumClass.getEnumConstants(); + if (constants == null || constants.length == 0) { + return Optional.empty(); + } + + StringJoiner joiner = new StringJoiner(", ", ENUM_VALUES_PREFIX, ""); + for (Object constant : constants) { + Enum enumValue = (Enum) constant; + Object code = ((CodeEnum) constant).getCode(); + joiner.add(String.valueOf(code) + "(" + enumValue.name() + ")"); + } + return Optional.of(joiner.toString()); + } + + public static Map> collectComponentEnumClasses(Map schemas) { + Map> enumClasses = new LinkedHashMap<>(); + if (schemas == null || schemas.isEmpty()) { + return enumClasses; + } + + for (Map.Entry entry : schemas.entrySet()) { + Schema schema = entry.getValue(); + if (schema == null || schema.getExtensions() == null) { + continue; + } + + Object className = schema.getExtensions().get(ENUM_CLASS_EXTENSION); + if (!(className instanceof String fqcn) || fqcn.isBlank()) { + continue; + } + + try { + Class clazz = Class.forName(fqcn); + if (isCodeEnumClass(clazz)) { + enumClasses.put(entry.getKey(), clazz); + } + } catch (ClassNotFoundException ignored) { + } + } + return enumClasses; + } + + private static Object firstCodeValue(Class enumClass) { + return Arrays.stream(enumClass.getEnumConstants()) + .map(constant -> ((CodeEnum) constant).getCode()) + .findFirst() + .orElse(null); + } + + private static String[] enumNames(Class enumClass) { + return Arrays.stream(enumClass.getEnumConstants()) + .map(constant -> ((Enum) constant).name()) + .toArray(String[]::new); + } + + @SuppressWarnings({"rawtypes", "unchecked"}) + private static void applyEnumCodes(Schema schema, Class enumClass) { + List enumCodes = Arrays.stream(enumClass.getEnumConstants()) + .map(constant -> ((CodeEnum) constant).getCode()) + .map(Object.class::cast) + .toList(); + schema.setEnum(enumCodes); + } + + private static String[] enumDescriptions(Class enumClass) { + return Arrays.stream(enumClass.getEnumConstants()) + .map(constant -> { + Enum enumValue = (Enum) constant; + Object code = ((CodeEnum) constant).getCode(); + return String.valueOf(code) + "(" + enumValue.name() + ")"; + }) + .toArray(String[]::new); + } + + private static void applyCodeType(Schema schema, Object code) { + if (code == null) { + return; + } + + if (code instanceof Byte || code instanceof Short || code instanceof Integer) { + schema.setType("integer"); + schema.setFormat("int32"); + return; + } + + if (code instanceof Long) { + schema.setType("integer"); + schema.setFormat("int64"); + return; + } + + if (code instanceof Float || code instanceof Double) { + schema.setType("number"); + schema.setFormat(code instanceof Float ? "float" : "double"); + return; + } + + if (code instanceof Number) { + schema.setType("number"); + return; + } + + if (code instanceof Boolean) { + schema.setType("boolean"); + return; + } + + schema.setType("string"); + schema.setFormat(null); + } + + private static boolean isCodeEnumClass(Class clazz) { + return clazz != null + && clazz.isEnum() + && CodeEnum.class.isAssignableFrom(clazz); + } + + private static String mergeDescription(String original, String enumDescription) { + if (original == null || original.isBlank()) { + return enumDescription; + } + + if (original.contains(enumDescription)) { + return original; + } + + return original + System.lineSeparator() + enumDescription; + } +}