[REQ][KOTLIN-SPRING] Add an opt-in generic `ResponseEntity` return type

[c19yamamoto]

Is your feature request related to a problem? Please describe.

The kotlin-spring generator cannot represent an operation whose successful responses have different body shapes when one response has no body.

For example, this operation can return either 201 Created with no body or 202 Accepted with an OperationStatusResponse body:

openapi: 3.0.3
info:
  title: Generic response entity reproduction
  version: 1.0.0
paths:
  /operations:
    post:
      operationId: startOperation
      responses:
        '201':
          description: Operation completed successfully
        '202':
          description: Operation accepted for asynchronous processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
components:
  schemas:
    OperationStatusResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string

With useResponseEntity=true, the generated method is:

fun startOperation(): ResponseEntity<Unit>

The type is derived from the 201 response, which has no content, so an implementation cannot return the response body for 202.

Describe the solution you'd like

Please add an opt-in option, similar to Java Spring's generateGenericResponseEntity, for example:

generateGenericResponseEntity=true

The generated method could use:

fun startOperation(): ResponseEntity<*>

or an equivalent type such as ResponseEntity<Any?>.

The option should be disabled by default and preserve the current behavior when disabled. All declared response annotations should also be preserved.

Describe the solution you'd like

Add a generateGenericResponseEntity option with two modes:

• NEVER (default): preserve the existing return types.
• ALWAYS: generate ResponseEntity<*> for all API methods.

For example:

generateGenericResponseEntity=ALWAYS

fun startOperation(): ResponseEntity<*>

The option should have no effect when useResponseEntity=false. All declared response annotations should be preserved.

String modes leave room for future extensions. Per-operation overrides and automatic detection are outside the scope of this request.

Additional context

Reproduced locally with:

OpenAPI Generator: 7.26.0-SNAPSHOT
Commit: 08919b294bd
Generator: kotlin-spring

Related Java Spring implementation: #21387
Implementation: #24805.

[Picazsoo]

One suggestion on scope: rather than a global boolean generateGenericResponseEntity flag, it would be better to drive this from a per-operation vendor extension (e.g. x-generic-response-entity), and to make the global option a string mode rather than a boolean.

The reason is type safety. A global on/off flag fixes the multiple-response-type problem by switching every operation to ResponseEntity<*>, including the ones that only ever return a single shape and were already correctly typed. Scoping it per operation lets you apply ResponseEntity<*> only where an operation actually has multiple response shapes, and leaves everything else strongly typed.

A string option could express this directly, for example:

• ALWAYS: use the generic type on every operation (the current PR behavior).
• WHEN_NEEDED_SUCCESS: auto-detect based on 2xx responses only, and use the generic type when those have differing shapes. This assumes 4xx/5xx are handled via @ControllerAdvice/@ExceptionHandler and never appear in the return type, which is the common Spring setup.
• WHEN_NEEDED_SUCCESS_AND_FAILURE: auto-detect considering all declared responses, for projects that return error bodies through the return type.
• NONE: never use the generic type (current default).

The per-operation x-generic-response-entity extension would still work as an explicit override on top of the chosen mode.

The distinction between the two WHEN_NEEDED variants matters because of exception handling. If detection counted all declared responses, an operation like 200 User + 404 + 500 would be pushed to ResponseEntity<*> even though only the 200 is a real return body, so ResponseEntity<User> is correct. The issue's own repro is the true positive: 201 with no body plus 202 with a body are both success responses with genuinely different shapes.

This also follows existing patterns in the generator. useSealedResponseInterfaces already works by stamping a per-operation x-sealed-response-interface extension that the templates key off (rather than the flag directly), and string-enum options like enumPropertyNaming are common too. So this stays predictable and consistent with how the generator already models options and response typing.

[Picazsoo]

Just to not gatekeep - I think a global on/off is a good start and it might satisfy the need for a majority of the users - I would just maybe already start with "NEVER"/"ALWAYS" instead of false/true, so that there is a possibility for the extension in the future! Also no need to do it through the x-generic-response-entity - that can always be done later when the finer granularity options are introduced.

[c19yamamoto]

@Picazsoo

Thanks for the suggestion! I’ve updated both this issue and #24805 to use NEVER (default) / ALWAYS instead of a boolean, leaving room for future modes. Per-operation overrides and automatic detection can follow later.