[kotlin-spring] Add type-safe response handling with sealed interfaces for multiple status codes

[louislepper]

The Problem:

Currently, when a Kotlin Spring endpoint returns different response types for different status codes, there's no type-safe way to represent this in the generated interface. Controllers must use unsafe casts or return a generic supertype, losing compile-time type safety.

Current Behavior:

Given an OpenAPI spec with multiple response types:

paths:
  /users:
    post:
      operationId: createUser
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '409':
          description: Conflict - User already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

The generated interface returns only the 200 response type:

interface DefaultApi {
    fun createUser(@Valid @RequestBody request: CreateUserRequest): ResponseEntity<User>
}

This forces implementations to use unsafe casts when returning non 2xx responses in controllers.

A Possible Solution:

Kotlin provides sealed interfaces, which feel like a good solution to this:

// Generated sealed interface
sealed interface CreateUserResponse

// Generated models implement the sealed interface
data class User(...) : CreateUserResponse
data class ConflictResponse(...) : CreateUserResponse
data class ErrorResponse(...) : CreateUserResponse

// Generated API uses sealed interface
interface DefaultApi {
    fun createUser(@Valid @RequestBody request: CreateUserRequest): ResponseEntity<CreateUserResponse>
}

This way our controllers can return any response code while maintaining compile time safety

@RestController
class UserController : DefaultApi {
    override fun createUser(request: CreateUserRequest): ResponseEntity<CreateUserResponse> {
        if (userExists(request.email)) {
            val response: CreateUserResponse = ConflictResponse(
                reason = ConflictReason.EMAIL_CONFLICT,
                message = "User already exists"
            )
            return ResponseEntity.status(409).body(response)
        }

        if (invalid(request)) {
            val response: CreateUserResponse = ErrorResponse(
                code = "INVALID_INPUT",
                message = "Invalid request"
            )
            return ResponseEntity.status(400).body(response)
        }

        val response: CreateUserResponse = User(...)
        return ResponseEntity.ok(response)
    }
}

[Picazsoo]

I would expect that any non-happy path such as 400 or 409 is solved via exception flows and @ControllerAdvice?. At least that's how I was taught.

[Mattias-Sehlstedt]

My understanding is the same as Picazsoo's, and that any response that is not 2xx is generally handled with the ControllerAdvice and that any exception is automatically converted to a semi-generic response body that contains an automatically generated ref-id and at most a short string that may give the user a slight idea of what went wrong.

I.e., the controller is only responsible for the actual business logic. Returning a ConflictResponse is not done by the controller, but any handling of errors is instead isolated to a component that collects any shared "exception X can actually provide data useful to the user"-logic for the few cases when an exception should not be a generic 500 that does not leak any information at all.

And if the controller wants to produce a 4xx or 5xx response itself, then it does so by throwing an exception for the ControllerAdvice (rather than instantiating a ConflictResponse and trying to return that itself).

Could we give a concrete example for a scenario when this new solution is suitable?