如何让Swagger JAX-RS生成共享枚举引用（Kotlin+Jersey场景）

针对你遇到的枚举被重复内联的问题，以下是几种可行的解决方法：

1. 给枚举类添加@Schema注解显式声明 #

在DataType枚举类上添加@Schema注解，明确将其标记为独立的Schema组件，同时指定类型为字符串（符合OpenAPI规范中枚举的定义）：

import io.swagger.v3.oas.annotations.media.Schema

@Schema(description = "数据类型枚举", type = "string")
enum class DataType {
    FIRST, SECOND
}

另外注意，Kotlin数据类的构造函数参数需要用val声明，才能生成可被Swagger识别的属性：

data class Data1(val type: DataType)
data class Data2(val type: DataType)

2. 配置Swagger扫描范围，确保枚举类被纳入 #

如果Swagger没有扫描到枚举类所在的包，就不会将其注册为全局组件。可以通过编程或注解方式配置扫描范围：

编程式配置 #

在Swagger的初始化监听器中指定扫描包：

import io.swagger.v3.jaxrs2.integration.OpenApiConfiguration
import io.swagger.v3.jaxrs2.integration.SwaggerServlet
import javax.servlet.ServletContextEvent
import javax.servlet.ServletContextListener

class SwaggerConfigListener : ServletContextListener {
    override fun contextInitialized(sce: ServletContextEvent?) {
        val config = OpenApiConfiguration()
        // 替换为你的枚举和DTO所在的包
        config.addScanPackage("com.yourpackage.enums")
        config.addScanPackage("com.yourpackage.dtos")
        
        SwaggerServlet().init(sce?.servletContext, config)
    }
}

注解式配置 #

在JAX-RS应用类上通过@OpenAPIDefinition显式注册组件：

import io.swagger.v3.oas.annotations.OpenAPIDefinition
import io.swagger.v3.oas.annotations.components.Components
import io.swagger.v3.oas.annotations.components.Schemas
import javax.ws.rs.ApplicationPath
import javax.ws.rs.core.Application

@OpenAPIDefinition(
    components = Components(
        schemas = [
            Schemas(value = DataType::class),
            Schemas(value = Data1::class),
            Schemas(value = Data2::class)
        ]
    )
)
@ApplicationPath("/api")
class MyApplication : Application()

3. 升级Swagger版本（可选） #

你当前使用的swagger-jaxrs2-jakarta:2.2.6版本对Kotlin特性的支持相对有限，升级到2.2.15及以上版本，能更好地兼容Kotlin数据类和枚举的解析，减少此类问题。

核心逻辑 #

Swagger默认会将未被显式标记或未被扫描到的枚举内联到属性定义中。当枚举被注册为全局组件后，Data1和Data2的type属性会通过$ref引用该全局枚举Schema，从而实现复用，避免客户端生成重复的枚举类。

内容的提问来源于stack exchange，提问作者dmitryvim