配置SpringDoc文档枚举值以及描述

配置SpringDoc文档枚举值以及描述

创建自定义枚举 IEnum

import java.io.Serializable

/**
 * 通用枚举接口，定义了枚举的基本行为和属性。
 *
 * @param <V> 枚举值的类型，该类型需实现Serializable接口，以便于序列化和反序列化。
 * @param <E> 子枚举类型，指明实现该接口的具体枚举类。
 */
interface IEnum<V : Serializable> {

    /**
     * 获取枚举项的值。该属性被[@JsonValue]注解标记，用于在JSON序列化和反序列化时使用。
     */
    @get:JsonValue
    val value: V

    /**
     * 从值反序列化枚举。这是一个companion object方法，用于根据提供的值查找并返回对应的枚举常量。
     *
     * @param value 要查找的枚举值。
     * @param B 实现IEnum接口的枚举类。
     * @return 找到的枚举常量，如果未找到则返回null。
     */
    companion object {
        inline fun <reified B, V> Class<B>.fromValue(value: V): B?
                where B : IEnum<V>, V : Serializable {
            return enumConstants?.asSequence()
                ?.filter { it.value == value } // 筛选出值匹配的枚举常量
                ?.firstOrNull() // 获取第一个匹配项，若无则返回null
        }
    }
}

创建工具类

import io.swagger.v3.core.util.PrimitiveType
import io.swagger.v3.oas.models.media.ObjectSchema
import io.swagger.v3.oas.models.media.Schema
import org.springframework.beans.BeanUtils
import org.springframework.util.ReflectionUtils
import java.lang.reflect.Modifier
import java.lang.reflect.Type

/**
 * IEnum枚举自定义器接口，提供操作枚举的自定义方法
 * @see IEnum
 */
interface IEnumCustomizer {

    /**
     * 获取枚举的所有值
     *
     * @param enumClazz 枚举的class
     * @return 枚举的所有值列表
     */
    fun getValues(enumClazz: Class<*>): List<Any> {
        // 通过反射获取枚举类的所有常量
        return enumClazz.enumConstants
            .mapNotNull { item ->
                // 收集每个枚举值的"getValue"方法返回的值
                val getValue = ReflectionUtils.findMethod(item.javaClass, "getValue")
                getValue?.let {
                    ReflectionUtils.makeAccessible(it)
                    ReflectionUtils.invokeMethod(it, item)
                }
            }
    }

    /**
     * 获取枚举值和对应描述的字符串表示
     *
     * @param enumClazz 枚举的class
     * @return 描述信息字符串
     */
    fun getDescription(enumClazz: Class<*>): String {
        // 获取枚举类中非静态字段，并按名称降序排序
        val fieldList = enumClazz.declaredFields
            .filter { !Modifier.isStatic(it.modifiers) }
            .sortedByDescending { it.name }

        // 使所有字段可访问
        fieldList.forEach { ReflectionUtils.makeAccessible(it) }

        // 构建每个枚举值及其字段描述的字符串
        return enumClazz.enumConstants
            .filterNotNull().joinToString("； ") { item ->
                fieldList.joinToString(" : ") { field ->
                    field.get(item).toString()
                }
            }
    }

    /**
     * 根据枚举值的类型获取相应的Swagger Schema对象
     *
     * @param type         枚举值的类型
     * @param sourceSchema 从属性中加载的原始Schema对象
     * @return 枚举值类型对应的Schema对象
     */
    fun getSchemaByType(type: Type, sourceSchema: Schema<*>): Schema<Any> {
        // 根据枚举值类型决定使用哪种类型的Schema
        val schema = PrimitiveType.fromType(type)?.createProperty()
            ?: ObjectSchema()

        // 复制原始schema的属性到新schema
        BeanUtils.copyProperties(sourceSchema, schema)

        // 返回配置好的schema
        return schema
    }
}

创建SpringDoc参数自定义配置

import io.swagger.v3.oas.models.media.Schema
import io.swagger.v3.oas.models.parameters.Parameter
import org.springdoc.core.customizers.ParameterCustomizer
import org.springframework.core.MethodParameter
import org.springframework.stereotype.Component

/**
 * 枚举参数自定义配置类。用于为API枚举参数提供自定义配置，包括参数描述和枚举值的设置。
 */
@Component
class ApiEnumParameterCustomizer : ParameterCustomizer, IEnumCustomizer {

    /**
     * 自定义API参数配置。
     * @param parameterModel API参数模型，用于配置参数属性。
     * @param methodParameter 方法参数，表示当前被解析的方法参数信息。
     * @return 返回经过自定义配置后的参数模型。如果未进行任何修改，则返回原始参数模型。
     */
    override fun customize(parameterModel: Parameter?, methodParameter: MethodParameter): Parameter? {
        val parameterType = methodParameter.parameterType
        parameterModel?.let {
            // 检查当前参数类型是否为枚举类型
            if (IEnum::class.java.isAssignableFrom(parameterType)) {
                // 设置参数描述
                it.description = getDescription(parameterType)
                // 配置参数的枚举值
                val schema = Schema<Any>()
                schema.enum = getValues(parameterType)
                it.schema = schema
            }
        }
        return parameterModel
    }
}

创建SpringDoc属性自定义配置

import com.fasterxml.jackson.databind.type.SimpleType
import io.swagger.v3.core.converter.AnnotatedType
import io.swagger.v3.oas.models.media.Schema
import org.springdoc.core.customizers.PropertyCustomizer
import org.springframework.stereotype.Component
import org.springframework.util.ObjectUtils
import java.lang.reflect.ParameterizedType

/**
 * 枚举属性自定义配置类，用于定制Swagger文档中枚举类型的展示方式。
 */
@Component
class ApiEnumPropertyCustomizer : PropertyCustomizer, IEnumCustomizer {

    /**
     * 自定义Swagger字段的枚举展示。
     * @param property Swagger字段模型
     * @param type 字段的注解类型
     * @return 修改后的Swagger字段模型
     */
    override fun customize(property: Schema<*>, type: AnnotatedType): Schema<*> {
        // 检查类型是否为SimpleType并获取实际字段类
        if (type.type is SimpleType) {
            val fieldClazz = (type.type as SimpleType).rawClass

            // 检查字段类是否为枚举
            if (IEnum::class.java.isAssignableFrom(fieldClazz)) {
                // 获取枚举的父接口，用于解析枚举值的类型
                val genericInterfaces = fieldClazz.genericInterfaces
                if (genericInterfaces.isNotEmpty() && genericInterfaces[0] is ParameterizedType) {
                    // 解析枚举值的实际类型
                    val actualTypeArgument = (genericInterfaces[0] as ParameterizedType).actualTypeArguments[0]
                    val schema = getSchemaByType(actualTypeArgument, property)

                    // 设置枚举的值和描述
                    schema.enum = this.getValues(fieldClazz)
                    val description = this.getDescription(fieldClazz)
                    schema.description = if (ObjectUtils.isEmpty(property.description)) description else "${property.description} ($description)"

                    return schema
                }
            }
        }
        return property
    }
}