codegen: Disambiguate when shared response model shared between multiple codes in same group, and handle 'default' error codes (#5370)

Closing #5284 and
#5286

Re-uses the same 'wrapper' declarations we use for response headers, to
handle the case where two status codes for the same method declare the
same response body. This approach _does_ mean that there's a bunch of
`sealed traits`s that get created for such endpoints, but they all
inherit from the same parent `StatusCodeDisambig`. A given code is
represented by a single object which inherits from the trait for each
endpoint that can return that code. This permits some generic handling
of errors.

Example generated code:

```scala
  sealed trait StatusCodeDisambig

  sealed trait DeleteInlineSimpleObjectResponseCode extends StatusCodeDisambig
  sealed trait DeleteInlineSimpleObjectResponseErrCode extends StatusCodeDisambig

  case object StatusCodeDisambig200
    extends DeleteInlineSimpleObjectResponseCode
  case object StatusCodeDisambig201
    extends DeleteInlineSimpleObjectResponseCode
  case object StatusCodeDisambig400
    extends PutInlineSimpleObjectResponseErrCode
  case object StatusCodeDisambig401
    extends DeleteInlineSimpleObjectResponseErrCode
    with PutInlineSimpleObjectResponseErrCode
  case object StatusCodeDisambig402
    extends DeleteInlineSimpleObjectResponseErrCode


  type DeleteInlineSimpleObjectEndpoint = Endpoint[Unit, Unit, DeleteInlineSimpleObjectResponseErrCode, DeleteInlineSimpleObjectResponseCode, Any]
  lazy val deleteInlineSimpleObject: DeleteInlineSimpleObjectEndpoint =
    endpoint
      .delete
      .in(("inline" / "simple" / "object"))
      .errorOut(oneOf[DeleteInlineSimpleObjectResponseErrCode](
        oneOfVariantValueMatcher(sttp.model.StatusCode(401), emptyOutput.description("empty response 3").and(emptyOutputAs(StatusCodeDisambig401))){ case StatusCodeDisambig401 => true},
        oneOfVariantValueMatcher(sttp.model.StatusCode(402), emptyOutput.description("empty response 4").and(emptyOutputAs(StatusCodeDisambig402))){ case StatusCodeDisambig402 => true}))
      .out(oneOf[DeleteInlineSimpleObjectResponseCode](
        oneOfVariantValueMatcher(sttp.model.StatusCode(200), emptyOutput.description("empty response 1").and(emptyOutputAs(StatusCodeDisambig200))){ case StatusCodeDisambig200 => true},
        oneOfVariantValueMatcher(sttp.model.StatusCode(201), emptyOutput.description("empty response 2").and(emptyOutputAs(StatusCodeDisambig201))){ case StatusCodeDisambig201 => true}))
  
```

for an endpoint declared as

```yaml
  '/inline/simple/object':
    delete:
      responses:
        "200":
          description: empty response 1
        "201":
          description: empty response 2
        "401":
          description: empty response 3
        "402":
          description: empty response 4
```


This handles 'default' codes by mapping to a case class wrapper rather
than an object. So, for
```yaml
...
      responses:
        "204":
          description: "No response"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        default:
          description: Generic error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
```
you get

```scala
  ...
  case class StatusCodeDisambigDefault(code: sttp.model.StatusCode)
    extends GetOneofErrorSecParamTestResponseErrCode
    ...
    .errorOut(oneOf[(Error, GetOneofErrorSecParamTestResponseErrCode)](
        oneOfVariantValueMatcher(sttp.model.StatusCode(404), jsonBody[NotFoundError].description("Not found").and(emptyOutputAs(StatusCodeDisambig404))){ case (_: NotFoundError, StatusCodeDisambig404) => true },
        oneOfVariantValueMatcher(jsonBody[SimpleError].description("Generic error").and(statusCode.map(StatusCodeDisambigDefault(_))(_.code))){ case (_: SimpleError, (_: StatusCodeDisambigDefault)) => true }))
      .out(statusCode(sttp.model.StatusCode(204)).description("No response"))
   
```

(if no other 'competing' error codes, a default is more simply
reducable, and ends up as just e.g.
`.errorOut(jsonBody[SimpleError].description("Generic
error").and(statusCode))`, but is still included as a param in the error
param type)


which I think is pretty good? I really wanted to explicitly avoid
passing around a raw status code since it wasn't type-safe in terms of
the status codes that can be represented on an endpoint... The shared
parent trait and common 'tuple companions' make generic handling
relatively nice, from what I've tried.


Added a behaviour flag with default false so as to not break existing
code.

One issue with this is that if you had, say, 400, 401 and 403, and the
400 had a different response type, you'd still have that extra status
code param for the 400 response, even though we could disambiguate
without it. Also you can cause a match error at runtime by specifying a
status code valid for a response of a different type. But it's a real
pain to codegen something that'll work better here, because you still
need that unified parent type -- so you'd need to introduce proper
wrappers, rather than just tupling it... Since by far the most common
use-case for this functionality is gonna be error responses, all the
real specs I've seen that don't already have different json schemas for
different error status codes use the same model for all error codes, and
since generic handling becomes a bit more of a faff with wrappers rather
than pairs, I think this still works out pretty well, so I'm happy
enough with it.

Author: hughsimpson

doc/generator/sbt-openapi-codegen.md

@@ -58,6 +58,8 @@ openapiPackageDependencies            Map.empty[String, String]            Allow
                                                                            to a Map[String, Seq[String]] in the near future to permit multiple 'inheritance', and there may be bugs in the implementation.
 openapiSeperateFilesForModels         false                                When true, models will be written to individual files under $pkg.models, with type aliases and helpers living under `package.scala` in a package object
 openapiAlwaysGenerateParamSupport     false                                When true, all enums will be generated with param & json support, even if not used in those positions. This is useful for definitions that will be reused with `openapiPackageDependencies`
+openapiAddDisambiguationCodes         false                                When true, if multiple status codes in same group (i.e. all error, or all success) return the same schema, they will be paired with a status code object as (T, StatusCode).
+                                                                           'Default' codes will map to an additional StatusCode output. When false, the type will remain a T and default codes will be treated as 400s.
 ===================================== ==================================== ==================================================================================================
 ```
 

openapi-codegen/core/src/main/scala/sttp/tapir/codegen/RootGenerator.scala

@@ -36,7 +36,8 @@ object RootGenerator {
       useCustomJsoniterSerdes: Boolean,
       packageReuse: PackageReuseContext,
       seperateFilesForModels: Boolean,
-      alwaysGenerateParamSupport: Boolean
+      alwaysGenerateParamSupport: Boolean,
+      addDisambiguationCodes: Boolean = true
   ): GenerationInfo = {
     val doc = unNormalisedDoc.resolveAllOfSchemas
     NameValidation.validateDocumentNames(doc, useHeadTagForObjectNames)
@@ -83,7 +84,7 @@ object RootGenerator {
       endpointsByTag,
       queryOrPathParamRefs,
       enumsDefinedOnEndpointParams,
-      EndpointDetails(jsonParamRefs, inlineDefns, xmlParamRefs, securityWrappers)
+      EndpointDetails(jsonParamRefs, inlineDefns, xmlParamRefs, securityWrappers, _)
     ) =
       endpointGenerator.endpointDefs(
         doc,
@@ -96,7 +97,8 @@ object RootGenerator {
         validators,
         generateValidators,
         packageReuse,
-        seperateFilesForModels
+        seperateFilesForModels,
+        addDisambiguationCodes
       )
     val modelPackagePath = s"$packagePath.models"
     val GeneratedClassDefinitions(

openapi-codegen/core/src/main/scala/sttp/tapir/codegen/endpoints/EndpointGenerator.scala

@@ -4,6 +4,7 @@ import io.circe.Json
 import sttp.tapir.codegen.dedup.PackageReuseContext
 import sttp.tapir.codegen.endpoints.SimpleTypes.mapSchemaSimpleTypeToType
 import sttp.tapir.codegen.endpoints.InAndOutComponents._
+import sttp.tapir.codegen.endpoints.OutComponent.{generateSharedStatusCodeDisambiguators, statusCodeDisambigBaseTrait}
 import sttp.tapir.codegen.json.JsonSerdeLib.JsonSerdeLib
 import sttp.tapir.codegen.openapi.models._
 import sttp.tapir.codegen.openapi.models.GenerationDirectives._
@@ -35,13 +36,15 @@ case class EndpointDetails(
     jsonParamRefs: Set[String],
     inlineDefns: Seq[String],
     xmlParamRefs: Set[String],
-    securityWrappers: Set[SecurityWrapperDefn]
+    securityWrappers: Set[SecurityWrapperDefn],
+    statusCodeDisambig: Seq[(String, String)] = Nil
 ) {
   def merge(that: EndpointDetails) = EndpointDetails(
     jsonParamRefs ++ that.jsonParamRefs,
     inlineDefns ++ that.inlineDefns,
     xmlParamRefs ++ that.xmlParamRefs,
-    securityWrappers ++ that.securityWrappers
+    securityWrappers ++ that.securityWrappers,
+    statusCodeDisambig ++ that.statusCodeDisambig
   )
 }
 object EndpointDetails {
@@ -86,7 +89,8 @@ class EndpointGenerator {
       validators: ValidationDefns,
       generateValidators: Boolean,
       packageReuse: PackageReuseContext,
-      seperateFilesForModels: Boolean
+      seperateFilesForModels: Boolean,
+      addDisambiguationCodes: Boolean
   ): EndpointDefs = {
     val capabilities = capabilityImpl(streamingImplementation)
     val components = Option(doc.components).flatten
@@ -109,10 +113,19 @@ class EndpointGenerator {
             validators,
             generateValidators,
             packageReuse,
-            seperateFilesForModels
+            seperateFilesForModels,
+            addDisambiguationCodes
           )
         )
         .foldLeft(GeneratedEndpoints(Nil, Set.empty, false, EndpointDetails.empty))(_ merge _)
+    val statusCodeDisambig = details.statusCodeDisambig.distinct
+    val inlineDefnsWithStatusCodeDisambig =
+      if (statusCodeDisambig.isEmpty) details.inlineDefns
+      else
+        Seq(s"sealed trait $statusCodeDisambigBaseTrait") ++ details.inlineDefns ++ generateSharedStatusCodeDisambiguators(
+          statusCodeDisambig
+        ).toSeq
+    val enrichedDetails = details.copy(inlineDefns = inlineDefnsWithStatusCodeDisambig)
     val endpointDecls = endpointsByFile.map { case GeneratedEndpointsForFile(maybeFileName, ge) =>
       val definitions = ge
         .map { case GeneratedEndpoint(name, definition, maybeInlineDefns, types) =>
@@ -137,7 +150,7 @@ class EndpointGenerator {
                            |$allEP
                            |""".stripMargin
     }.toMap
-    EndpointDefs(endpointDecls, queryOrPathParamRefs, definesEnumQueryParam, details)
+    EndpointDefs(endpointDecls, queryOrPathParamRefs, definesEnumQueryParam, enrichedDetails)
   }
 
   private[codegen] def generatedEndpoints(
@@ -151,7 +164,8 @@ class EndpointGenerator {
       validators: ValidationDefns,
       generateValidators: Boolean,
       packageReuse: PackageReuseContext,
-      seperateFilesForModels: Boolean
+      seperateFilesForModels: Boolean,
+      addDisambiguationCodes: Boolean
   )(p: OpenapiPath): GeneratedEndpoints = {
     val parameters = components.map(_.parameters).getOrElse(Map.empty)
     val securitySchemes = components.map(_.securitySchemes).getOrElse(Map.empty)
@@ -206,7 +220,7 @@ class EndpointGenerator {
               packageReuse,
               seperateFilesForModels
             )
-          val (outDecl, outTypes, errTypes, inlineDefns) =
+          val (outDecl, outTypes, errTypes, inlineDefns, statusCodeDisambig) =
             OutComponent.outs(
               m.responses.map(_.resolve(doc)),
               streamingImplementation,
@@ -220,7 +234,8 @@ class EndpointGenerator {
               generateValidators,
               isReused,
               packageReuse,
-              seperateFilesForModels
+              seperateFilesForModels,
+              addDisambiguationCodes
             )
           val allTypes = EndpointTypes(
             maybeSecurityPath.toSeq.flatMap(_._2) ++ securityTypes.toSeq,
@@ -280,7 +295,7 @@ class EndpointGenerator {
           (
             (maybeTargetFileName, GeneratedEndpoint(name, definition, maybeLocalEnums.filterNot(_ => isReused), allTypes)),
             (queryOrPathParamRefs, jsonParamRefs, xmlParamRefs),
-            (maybeLocalEnums.isDefined && !isReused, inlineDefn, securityWrappers)
+            (maybeLocalEnums.isDefined && !isReused, inlineDefn, securityWrappers, statusCodeDisambig)
           )
         } catch {
           case e: NotImplementedError => throw e
@@ -293,7 +308,10 @@ class EndpointGenerator {
       .groupBy(_._1)
       .toSeq
       .map { case (maybeTargetFileName, defns) => GeneratedEndpointsForFile(maybeTargetFileName, defns.map(_._2)) }
-    val (definesParams, inlineDefns, securityWrappers) = inlineParamInfo.unzip3
+    val definesParams = inlineParamInfo.map(_._1)
+    val inlineDefns = inlineParamInfo.map(_._2)
+    val securityWrappers = inlineParamInfo.map(_._3)
+    val statusCodeDisambigs = inlineParamInfo.map(_._4)
     GeneratedEndpoints(
       namesAndParamsByFile,
       unflattenedQueryParamRefs.foldLeft(Set.empty[String])(_ ++ _),
@@ -302,7 +320,8 @@ class EndpointGenerator {
         unflattenedJsonParamRefs.foldLeft(Set.empty[String])(_ ++ _),
         inlineDefns.flatten,
         xmlParamRefs.flatten.toSet,
-        securityWrappers.flatten.toSet
+        securityWrappers.flatten.toSet,
+        statusCodeDisambig = statusCodeDisambigs.flatten
       )
     )
   }
@@ -329,4 +348,4 @@ class EndpointGenerator {
 }
 
 case class MappedContentType(bodyImpl: String, bodyType: String, inlineDefns: Option[String] = None, inlineTypes: Seq[String] = Nil)
-case class MappedOutGroup(decls: Option[String], types: Option[String], defns: Option[String])
+case class MappedOutGroup(decls: Option[String], types: Option[String], defns: Option[String], statusCodeDisambig: Seq[(String, String)] = Nil)