Change of Documented Return Type

[itd-sw]

Describe the bug

If one derived a class from ResponseEntity, the documented return type used to be the generic passed to that derived class (2.6.0). When using 2.8.5, the documented class is the generic passed to ResponseEntity

To Reproduce
Steps to reproduce the behavior:

• spring-boot 3.4.3
• org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.5
• set springdoc.api-docs.version=openapi_3_0 in application.properties

Sample Code

import org.springframework.http.HttpHeaders
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@RestController
class SampleController {
    @GetMapping("/visible")
    fun visible(): VisibleApiResult<ApiResult<SampleResponse>> = VisibleApiResult(
        ApiResult(
            result = SampleResponse("foo")
        )
    )

    @GetMapping("/hidden")
    fun hidden(): HiddenApiResult<SampleResponse> = HiddenApiResult(
        ApiResult(
            result = SampleResponse("bar")
        )
    )
}

data class SampleResponse(val foo: String)

class HiddenApiResult<T>(result: ApiResult<T>) :
    ResponseEntity<ApiResult<T>>(result, null as HttpHeaders?, HttpStatus.OK)

class VisibleApiResult<T>(result: T) :
    ResponseEntity<T>(result, null as HttpHeaders?, HttpStatus.OK)


data class ApiResult<T>(val errors: String? = null, val result: T?)

Expected behavior
Schema when using spring doc 2.6.0

{
  "components": {
    "schemas": {
      "ApiResultSampleResponse": {
        "properties": {
          "errors": { "type": "string" },
          "result": { "$ref": "#/components/schemas/SampleResponse" }
        },
        "type": "object"
      },
      "SampleResponse": {
        "properties": { "foo": { "type": "string" } },
        "required": ["foo"],
        "type": "object"
      }
    }
  },
  "info": { "title": "OpenAPI definition", "version": "v0" },
  "openapi": "3.0.1",
  "paths": {
    "/hidden": {
      "get": {
        "operationId": "hidden",
        "responses": {
          "200": {
            "content": {
              "*/*": {
                "schema": { "$ref": "#/components/schemas/SampleResponse" }
              }
            },
            "description": "OK"
          }
        },
        "tags": ["sample-controller"]
      }
    },
    "/visible": {
      "get": {
        "operationId": "visible",
        "responses": {
          "200": {
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResultSampleResponse"
                }
              }
            },
            "description": "OK"
          }
        },
        "tags": ["sample-controller"]
      }
    }
  },
  "servers": [
    { "description": "Generated server url", "url": "http://localhost:8080" }
  ]
}

Schema when using spring doc 2.8.5

• both endpoints now return #/components/schemas/ApiResultSampleResponse

{
  "components": {
    "schemas": {
      "ApiResultSampleResponse": {
        "properties": {
          "errors": { "type": "string" },
          "result": { "$ref": "#/components/schemas/SampleResponse" }
        },
        "type": "object"
      },
      "SampleResponse": {
        "properties": { "foo": { "type": "string" } },
        "required": ["foo"],
        "type": "object"
      }
    }
  },
  "info": { "title": "OpenAPI definition", "version": "v0" },
  "openapi": "3.0.1",
  "paths": {
    "/hidden": {
      "get": {
        "operationId": "hidden",
        "responses": {
          "200": {
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResultSampleResponse"
                }
              }
            },
            "description": "OK"
          }
        },
        "tags": ["sample-controller"]
      }
    },
    "/visible": {
      "get": {
        "operationId": "visible",
        "responses": {
          "200": {
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResultSampleResponse"
                }
              }
            },
            "description": "OK"
          }
        },
        "tags": ["sample-controller"]
      }
    }
  },
  "servers": [
    { "description": "Generated server url", "url": "http://localhost:8080" }
  ]
}

Additional context
Is this change intentional? It was a simple way to hide the intermediate ApiResult class.
To keep the documented class, we could add an annotation, but this could lead to inconsistencies:

    @ApiResponse(
        content = [
            Content(
                schema = Schema(implementation = SampleResponse::class)
            )
        ]
    )
    fun hidden(): HiddenApiResult<SampleResponse> = HiddenApiResult(
    ...

If this change is intentional, what is the recommended way to hide such a class from documentation?

Thank you!

[bnasslahsen]

@itd-sw,

This change is intentional, as the result of 2.8.5, is the correct OpenAPI spec.
You can override the response, as you described by using @ApiResponse