OpenAPITools / OpenAPITools/openapi-generator

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

Open
#24,804 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

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: https://github.com/OpenAPITools/openapi-generator/pull/21387
Implementation: #24805.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the kotlin-spring generator's option handling and return-type generation, using the related Java Spring implementation in PR #21387 as context. Add the opt-in NEVER/ALWAYS behavior while preserving the default and declared response annotations; verify the example produces ResponseEntity<*> only when both options require it.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin, openapi, spring
Domain
backend-api-design, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.