Schema of `oneOf` variants with same status code and content-type

[susliko]

Schema of `oneOf` variants with same status code and content-type

[adamw]

Sorry for the late reply :)

In OpenAPI docs, we can only have a single output per status code. So while this will work server-side, the documentation will be inprecise.

I suspect that what you're after is having the body represented as a hierarchy. You can also then specify the discrimination strategy that you're using. So you'd need something as follows:

sealed trait A 
sealed trait Success extends A derives Schema, Encoder.AsObject, Decoder
case class B(b: String) extends Success 
case class C(c: String) extends Success
case object D extends A derives Schema, Encoder.AsObject, Decoder

@main
def tapirOneOf =
  val myEndpoint = endpoint.get
    .in("path")
    .out(oneOf[A](
      oneOfVariant(statusCode(StatusCode.Ok).and(jsonBody[Success])),
      oneOfVariant(statusCode(StatusCode.NoContent).and(jsonBody[D.type])),
    ))

Relevant documentation sections:
https://tapir.softwaremill.com/en/latest/endpoint/oneof.html
https://tapir.softwaremill.com/en/latest/endpoint/schemas.html#sealed-traits-coproducts

[susliko]

@adamw Thanks for the reply :)

What I meant here is that the schema, which is generated for the case with multiple oneOfVariant for the same status code, is already imprecise: it lacks the 200 B case, while the code compiles and runs well (here's a runnable gist). And it was an unexpected behavior for me (I expected oneOf schema with variants B and C to be generated for the 200 application/json response).

I do realize that tailoring response type hierarchies to the status codes solves this, but it's a constraint which is not tracked in compile time and hence is easy to violate.

[adamw]

Yes, I can see that it might be problematic. I suppose we could create an inline oneOf or anyOf schema for such cases (where there are multiple oneOfVariants for a single status code).

[susliko]

Great, I'll make a pr

[adamw]

Awesome :) I suspect the root of the problem is the .headOption here:

tapir/docs/openapi-docs/src/main/scala/sttp/tapir/docs/openapi/EndpointToOpenAPIPaths.scala

Line 58 in 02978cd

requestBody = body.headOption,