Recursive Object References Not Working in OpenAPI 3.1

[georgslazdans]

Describe the bug

Recursive object references are broken in Kotlin WebFlux with OpenAPI 3.1 and give out empty schema definition instead of a reference to itself.

They are working fine with OpenAPI 3.0, either by using older springdoc version or setting OpenAPI version in application yaml file.

Have not tested this with regular Java or Web MVC

To Reproduce
Steps to reproduce the behavior:

build.gradle.kts

plugins {
  id("org.jetbrains.kotlin.jvm")
  id("org.jetbrains.kotlin.plugin.spring")
  id("org.springframework.boot")
  id("org.springdoc.openapi-gradle-plugin")
}

kotlin {
  jvmToolchain(21)
  compilerOptions {
    freeCompilerArgs.addAll("-Xjsr305=strict")
  }
}

dependencies {
  implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.1.20"))
  implementation(platform(SpringBootPlugin.BOM_COORDINATES))
  implementation("org.springframework.boot:spring-boot-starter-webflux")
  implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.8.9")
}

openApi {
  apiDocsUrl.set("http://localhost:8888/doc/openapi")
  outputDir.set(layout.projectDirectory.dir("src/main/resources/openapi"))
  customBootRun {
    args.set(listOf("--spring.profiles.active=openapigen"))
  }
}

RecursiveTestModel

@Schema
data class RecursiveTestModel(
  val name: String,
  val child: RecursiveTestModel?,
  val children: List<RecursiveTestModel>,
)

TestController

@RestController
@RequestMapping("/api")
class TestController {
  @GetMapping("/recursive-test-data")
  @Schema
  fun getRecursiveTestData(): Mono<RecursiveTestModel> = Mono.just(
    RecursiveTestModel(
      name = "test",
      child =  null,
      children = listOf()
    )
  )
}

Resulting behavior (OpenAPI 3.1.0)

      "RecursiveTestModel": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "child": {},
          "children": {
            "type": "array",
            "items": {}
          }
        }
      }

Expected behavior (OpenAPI 3.0.1)

      "RecursiveTestModel": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "child": {
            "$ref": "#/components/schemas/RecursiveTestModel"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecursiveTestModel"
            }
          }
        }
      }

[georgslazdans]

Small additional information - this behaviour seems to be introduced with version 2.8.7, but I falsely assumed it was just because of OpenAPI 3.1 version, since updated quite a few versions at once.

Using version 2.8.6 the OpenAPI 3.1 spec returns the expected result with correct $ref to itself.

[geirsagberg]

Try adding @JsonManagedReference:

@Schema
data class RecursiveTestModel(
  val name: String,
  val child: RecursiveTestModel?,
  @JsonManagedReference
  val children: List<RecursiveTestModel>,
)

did the trick for me