OpenAPITools / OpenAPITools/openapi-generator
[REQ][KOTLIN-SPRING] Add an opt-in generic `ResponseEntity` return type
Nobody has claimed this yet.
- 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: generateResponseEntity<*>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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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