Generated code for error clauses is stringly-typed

[jducoeur]

Context: https://softwaremill.community/t/how-best-to-go-about-proposing-and-helping-with-code-generation-improvements/542

Tapir version: 1.13.19

Given an OpenAPI spec including something like this:

responses:
  '200':
    description: Success
    content:
      text/plain:
        schema:
          type: string
          example: Success
  '400':
    description: Bad parameters
    content:
      text/plain:
        schema:
          type: string
          example: Example bad parameter message
  '404':
    description: Missing a bit
    content:
      text/plain:
        schema:
          type: string
          example: The missing details message
  '500':
    description: Failure
    content:
      text/plain:
        schema:
          type: string
          example: Failure

The generated errorOut clause looks like:

.errorOut(oneOf[String](
  oneOfVariant[String](sttp.model.StatusCode(400), stringBody.description("Bad parameters")),
  oneOfVariant[String](sttp.model.StatusCode(404), stringBody.description("Missing a bit")),
  oneOfVariant[String](sttp.model.StatusCode(500), stringBody.description("Failure"))))

The problem is, oneOfVariant is class-based according to the docs. Since all three of these are strings, anything returned will match the first one and produce a 400. You have to do some rather ugly and fragile hackery in the server logic to produce the desired return code.

Worse yet, if there is no description on one of those response codes, it assigns an empty string body as the marker, making it more or less impossible (AFAICT) for the serverLogic to produce the desired code!

All of this is pretty unfortunate from a logic POV. I want to be able to have my server logic produce the status code in the returned value, and have the string body not matter to the variant matching. The current approach forces the code to be stringly-typed, which makes my Scala-centric heart sad.

I'm happy to help work to make this enhancement happen, but we definitely need to talk about what the ideal outcome would look like, and how to get there without breaking existing Tapir users.

[adamw]

Tagging @hughsimpson - since it touches openapi-codegen and you're the expert there.

My initial instinct would be that in case there are overlapping types in the one-of branches, we need to generate wrappers (enum / sealed trait + cc), but maybe there are better ways.

[hughsimpson]

I have commented on this weakness before in some long-since merged prs. I kinda hacked away from it and solved it at a different level, but it's constantly nagged me. For header ambiguity, we have specific case classes. I don't love that but it's OK. Will see what it looks like.

[hughsimpson]

I say all that to say: I don't think there's a nice way. Maybe force a status int coparam if ambiguity?

[hughsimpson]

I think I'd settle for less than ambiguity. 'Possibly ambiguity' would be enough if not too inclusive. TBD.

[jducoeur]

I haven't studied the codegen code well enough to know feasibility (it could be a major headache to build), but I see two options offhand that would probably solve my problem:

• A feature flag that just flips table around -- the status code becomes the class that gets returned by the logic, and the oneOf clause gates on the exact value instead of the class. The message is hardcoded based on that.
• A feature flag that points to some sort of class or template that is instantiated with the OpenAPI parameters, to allow fuller customization.

That's all completely hand-wavey, but is basically the direction I'm thinking. (For all I know, there might already be a better solution and I just haven't seen it yet -- the NotAnIO discussion shows clearly that there are depths I haven't found yet.)

The heart of my objection here is to the stringly-typed return values from the business logic -- that's pretty fragile, especially given that neither "description" or "example" obviously means "this is the actual string being produced" to me. What I really want is to be able to not gate on the strings at all, but on the status code instead.

Anyway, if I can find my way through the bureaucratic thickets to be allowed to help with the code, hopefully I can get elbow-deep and come up with a PR.