260407_01_ENH: CodeEnum의 내용을 Swagger에 자동으로 표기하는 기능 추가

This commit is contained in:
2026-04-07 10:08:06 +09:00
parent 12b2b72121
commit 59f656b99b
5 changed files with 579 additions and 2 deletions

View File

@@ -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> swaggerIpFilter() {

View File

@@ -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<ModelConverter> 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;
}
}

View File

@@ -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<String, Class<?>> componentClasses;
public CodeEnumOpenApiCustomizer(String basePackage) {
this.basePackage = basePackage;
}
@Override
public void customise(OpenAPI openApi) {
if (openApi == null) {
return;
}
Map<String, Schema> schemas = openApi.getComponents() != null
? openApi.getComponents().getSchemas()
: null;
Map<String, Class<?>> componentEnumClasses = CodeEnumSwaggerSupport.collectComponentEnumClasses(schemas);
Map<String, Class<?>> componentDtoClasses = collectComponentClasses(schemas);
if (schemas != null) {
for (Map.Entry<String, Schema> 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<String, Class<?>> componentEnumClasses) {
if (content == null) {
return;
}
for (MediaType mediaType : content.values()) {
if (mediaType != null) {
applyToSchema(mediaType.getSchema(), componentEnumClasses);
}
}
}
private void applyToSchema(Schema<?> schema, Map<String, Class<?>> 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<String, Class<?>> componentEnumClasses) {
if (schema == null) {
return;
}
if (schema instanceof ArraySchema arraySchema) {
applyToSchema(arraySchema.getItems(), componentEnumClasses);
}
if (schema.getProperties() != null) {
Map<String, Schema> 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<Field> 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<String, Class<?>> collectComponentClasses(Map<String, Schema> schemas) {
if (schemas == null || schemas.isEmpty() || basePackage == null || basePackage.isBlank()) {
return Map.of();
}
if (componentClasses != null) {
return componentClasses;
}
Map<String, Class<?>> 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;
}
}
}

View File

@@ -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<Class<?>> resolveCodeEnumClass(AnnotatedType annotatedType) {
if (annotatedType == null) {
return Optional.empty();
}
return resolveCodeEnumClass(annotatedType.getType());
}
public static Optional<Class<?>> 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<Class<?>> 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<String> 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<String, Object> 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<String> enumDescription = getEnumDescription(schema);
return enumDescription
.map(description -> mergeDescription(original, description))
.orElse(original);
}
public static Optional<String> 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<String> 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<String, Class<?>> collectComponentEnumClasses(Map<String, Schema> schemas) {
Map<String, Class<?>> enumClasses = new LinkedHashMap<>();
if (schemas == null || schemas.isEmpty()) {
return enumClasses;
}
for (Map.Entry<String, Schema> 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<Object> 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;
}
}