springdoc开启use-fqn=true时oneOf关键字引发Swagger-UI解析错误

环境 #

springdoc-openapi-ui (1.6.12) + Kotlin

问题详情 #

我实现了如下简单RestController：

@RestController
class DemoController {
    @PostMapping
    fun Post(@RequestBody body: Body) {
        TODO()
    }
}

@Schema(oneOf = [Body1::class, Body2::class, Body3::class])
interface Body

data class Body1(
    val demo: Int
) : Body

data class Body2(
    val demo: Int
) : Body

data class Body3(
    val demo: Int
) : Body

同时在application.properties中配置：

springdoc.use-fqn=true

此时Swagger-ui显示以下错误：

Errors
Resolver error at paths./.post.requestBody.content.application/json.schema.oneOf.2.$ref
Could not resolve reference: undefined undefined
Resolver error at paths./.post.requestBody.content.application/json.schema.oneOf.1.$ref
Could not resolve reference: undefined undefined
Resolver error at paths./.post.requestBody.content.application/json.schema.oneOf.0.$ref
Could not resolve reference: undefined undefined

已尝试操作 #

尝试用全限定名（FQN）指定oneOf关键字的类，但仍出现错误。

期望结果 #

希望OpenAPI生成如下结构的Schema：

"components": {
        "schemas": {
            "com.example.demo.Body": {
                "type": "object",
                "oneOf": [
                    {
                        "$ref": "#/components/schemas/com.example.demo.Body1"
                    },
                    {
                        "$ref": "#/components/schemas/com.example.demo.Body2"
                    },
                    {
                        "$ref": "#/components/schemas/com.example.demo.Body3"
                    }
                ]
            },

我认为Schema引用应采用#/components/schemas/com.example.demo.BodyX格式。

疑问 #

我是否存在操作错误？若有，该如何修复这些错误？

解决方法 #

1. 给所有实现类显式配置@Schema的name属性

你的Body1/Body2/Body3未标记@Schema注解，在开启springdoc.use-fqn=true的情况下，旧版springdoc无法自动为Kotlin数据类生成正确的全限定名Schema。给每个实现类加上带FQN的name：

@Schema(name = "com.example.demo.Body1")
data class Body1(
    val demo: Int
) : Body

@Schema(name = "com.example.demo.Body2")
data class Body2(
    val demo: Int
) : Body

@Schema(name = "com.example.demo.Body3")
data class Body3(
    val demo: Int
) : Body

2. 升级springdoc-openapi-ui版本

你使用的1.6.12版本较旧，对Kotlin的oneOf场景支持存在缺陷。建议升级到2.x系列的稳定版，新版本修复了大量Kotlin相关的Schema解析问题，开启springdoc.use-fqn=true后会自动生成正确的全限定名引用格式，无需手动指定。

3. 验证配置

升级版本并添加注解后，重启服务，Swagger-ui的解析错误会消失，生成的Schema会自动采用#/components/schemas/com.example.demo.BodyX格式的引用，完全符合预期结构。

内容的提问来源于stack exchange，提问作者T.A