feat: add support for oneOf in sttp4 client

[plaflamme]

Address #19891 for sttp4 clients.

@Fish86

PR checklist

• Read the contribution guidelines.
• Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• If your PR solves a reported issue, reference it using GitHub's linking syntax (e.g., having "fixes #123" present in the PR description)
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

---

Summary by cubic

Adds oneOf support to the Scala scala-sttp4 client with discriminator mapping, wrapper composition for shared members, and aligned JSON/request/response handling. Updates docs, adds a scala-sttp4-circe sample and CI, bumps dependencies, fixes parent-with-properties and aliased-child cases, and adds tests (including keyword discriminator wire-name). Fixes #19891.

• New Features

  • oneOf: sealed-trait parents; inline or wrapper composition for children; discriminator + mapping; uses discriminator.propertyBaseName for correct wire field (handles Scala keywords); discriminator fields removed in children; empty-member handling; aliased children resolved; parent props enforced on the trait and propagated to each child; custom circe/json4s codecs; total constructor-name mapping; tests for edge cases.
  • API alignment: body(asJson(...)); Either[ResponseException[String], T]; pass Option[String] directly to .header; query/form containers encode via mkString(","); url-form-encoded bodies include only provided fields; default Seq params = Seq.empty; AnyType/object map to circe Json/JsonObject or json4s JValue/JObject.
  • Enums/samples/deps: enums use sealed-trait ADTs with per-type codecs (json4s JsonSupport now uses enum companion Serializer objects); new scala-sttp4-circe sample + CI; sttp client 4.0.15; Scala 2.13.18; add circe-generic and circe-generic-extras; use semiauto derivation.

• Migration

  • Enums are sealed traits; update matches/usages and imports.
  • oneOf parents are sealed traits; parent properties appear on the parent trait and each child; wrappers may exist under the parent companion; adjust usages/imports if referenced directly.
  • Response type is Either[ResponseException[String], T] (was ResponseException[String, Exception]).
  • Query/form containers now use mkString(","); url-form-encoded bodies omit unset fields; verify server expectations.

^{Written for commit 21efd98. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 8 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="modules/openapi-generator/src/main/resources/scala-sttp4/api.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/scala-sttp4/api.mustache:38">
P2: Request bodies are now always JSON‑serialized with `asJson(...)`, which breaks operations that consume non‑JSON media types by sending JSON instead of the raw body.</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache:52">
P2: json4s oneOf deserialization aborts on first mismatch because `Extraction.extract` throws, so later oneOf types are never tried.</violation>

<violation number="2" location="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache:74">
P2: Discriminator handling hardcodes the Scala class name as the wire value, ignoring OpenAPI discriminator mappings, so specs with mapped discriminator values will fail to deserialize/serialize correctly.</violation>

<violation number="3" location="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache:172">
P2: Inline oneOf member case classes are generated inside the parent model file, but the parent model’s import list isn’t augmented with the child models’ imports. If a oneOf member uses a type not referenced by the parent, the inline case class will compile without the necessary import.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[wing328]

thanks for the PR

cc @clasnake (2017/07), @shijinkui (2018/01), @ramzimaalej (2018/03), @chameleon82 (2020/03), @Bouillie (2020/04) @Fish86 (2023/06)

[wing328]

https://github.com/OpenAPITools/openapi-generator/actions/runs/21774387501/job/62832048821?pr=22916

please follow step 3 to update the samples

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache:107">
P2: `transformConstructorNames` is defined as a partial match over only `x-oneOfMembers`. Because `x-oneOfMembers` excludes shared oneOf subtypes, the function is not total and will throw `MatchError` when encoding/decoding those subtypes. Add a default case (identity) so unmapped constructor names don’t crash serialization.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[plaflamme]

@wing328 I've updated the samples in e594023

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache:110">
P2: Wildcard `case other` is emitted inside the oneOfMembers loop, so the first wildcard matches everything and makes subsequent member cases unreachable; only the first oneOf member can be encoded/decoded.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[wing328]

https://github.com/OpenAPITools/openapi-generator/actions/runs/21850815146/job/63223036192?pr=22916

please replace tabs with 4-space in the java file.

[plaflamme]

@wing328 should be all good now

[wing328]

please review the build failure when you've time.

let us know if you need any help

[plaflamme]

@wing328 I think this is good to go now?

[plaflamme]

@wing328 updated this on top of the latest master branch, anything else needed to get this in?

[wing328]

will try to run some tests tomorrow and merge if no questions/feedback from anyone.

[wing328]

i did a test with this spec:

 java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g scala-sttp4 -i https://raw.githubusercontent.com/plaflamme/openapi-generator/ac1b84e6a05e1bbfbfed7903aed15cc20fdb7c9b/modules/openapi-generator/src/test/resources/3_0/scala/sttp4-oneOf.yaml -o /tmp/scala3 --additional-properties jsonLibrary=circe --skip-validate-spec

but got compilation errors on the output:

$ sbt compile
[info] welcome to sbt 1.10.11 (Eclipse Adoptium Java 11.0.30)
[info] loading settings for project scala3-build from plugins.sbt...
[info] loading project definition from C:\Users\User\AppData\Local\Temp\scala3\project
[info] loading settings for project scala3 from build.sbt...
[info] set current project to openapi-client (in build file:/C:/Users/User/AppData/Local/Temp/scala3/)
[info] Executing in batch mode. For better performance use sbt's shell
[info] compiling 8 Scala sources to C:\Users\User\AppData\Local\Temp\scala3\target\scala-2.13\classes ...
[error] C:\Users\User\AppData\Local\Temp\scala3\src\main\scala\org\openapitools\client\core\JsonSupport.scala:19:66: not found: type DateSerializers
[error] object JsonSupport extends SttpCirceApi with AutoDerivation with DateSerializers with AdditionalTypeSerializers {
[error]                                                                  ^
[error] C:\Users\User\AppData\Local\Temp\scala3\src\main\scala\org\openapitools\client\model\Animal.scala:29:43: Could not find ConfiguredAsObjectEncoder for type org.openapitools.client.model.Animal.
[error] Some possible causes for this:
[error] - org.openapitools.client.model.Animal isn't a case class or sealed trait
[error] - some of org.openapitools.client.model.Animal's members don't have codecs of their own
[error] - missing implicit Configuration
[error]   implicit val encoder: Encoder[Animal] = deriveConfiguredEncoder
[error]                                           ^
[error] C:\Users\User\AppData\Local\Temp\scala3\src\main\scala\org\openapitools\client\model\Animal.scala:30:43: Could not find ConfiguredDecoder for type org.openapitools.client.model.Animal.
[error] Some possible causes for this:
[error] - org.openapitools.client.model.Animal isn't a case class or sealed trait
[error] - some of org.openapitools.client.model.Animal's members don't have codecs of their own
[error] - missing implicit Configuration
[error]   implicit val decoder: Decoder[Animal] = deriveConfiguredDecoder
[error]                                           ^
[error] C:\Users\User\AppData\Local\Temp\scala3\src\main\scala\org\openapitools\client\model\Pet.scala:22:40: could not find Lazy implicit value of type io.circe.generic.encoding.DerivedAsObjectEncoder[org.openapitools.client.model.Pet]
[error]   implicit val encoder: Encoder[Pet] = deriveEncoder
[error]                                        ^
[error] C:\Users\User\AppData\Local\Temp\scala3\src\main\scala\org\openapitools\client\model\Pet.scala:23:40: could not find Lazy implicit value of type io.circe.generic.decoding.DerivedDecoder[org.openapitools.client.model.Pet]
[error]   implicit val decoder: Decoder[Pet] = deriveDecoder
[error]                                        ^
[error] 5 errors found
[error] (Compile / compileIncremental) Compilation failed
[error] Total time: 4 s, completed Mar 22, 2026, 10:09:05 PM

can you please take a look when you've time?

[plaflamme]

@wing328 sorry for the delay, I've added 5a3afd8 to fix this and merged the master branch to check everything is working, I think this is good to go again

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/scala-sttp4/model.mustache:149">
P1: Circe oneOf encoder with wrapper composition does not add discriminator in discriminator mode, causing mismatch with decoder that requires discriminator.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}