swagger-api / swagger-api/swagger-codegen-generators

Better Handling of "oneOf" (and "anyOf") Constructs

Open
#687 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mustache
Stars
299
Forks
439
PR merge metrics
No merged PRs in 30d

Description

This is a feature request to better handle oneOf (and anyOf) constructs on OAS 3.x specifications. Currently, the generated models produce an empty interface and even some empty classes (especially where the oneOf involves a basic type like string and another type like an object class).

I am attaching a ZIP file with an example OAS YAML file as well as the model implementation that could be used as an alternative for Java. The contained README.md explains the issue and why I believe this model is better.

The usage for this pattern looks like this:

    Name name = new Name();
    name.setGivenName("Joe");
    name.setSurname("Schmoe");

    NameRepresentation asName = NameRepresentation.from(name);

    NameRepresentation asString = NameRepresentation.from("Joe Schmoe");

    List<NameRepresentation> names = List.of(asName, asString);

    for (NameRepresentation nameRep : names) {
      if (nameRep.is(Name.class)) {
        Name value = nameRep.as(Name.class);
        System.out.println("Name is " + value.getGivenName()
                           + " " + value.getSurname());

      } else if (nameRep.is(String.class)) {
        String value = nameRep.as(String.class);
        System.out.println("Name is " + value);

      } else {
        throw new IllegalStateException(
          "Unhandled value type: " + nameRep.getValueType());

      }  
    }

I am looking at modifying the code generator to produce this, but I may not have the time to make that effort in my job so I wanted to share with your team (as well as the OpenAPI Generator team) as an alternative
one-of-example.zip

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with one-of-example.zip, especially its README.md, example OAS YAML, and Java model implementation. Compare the current generated models for OAS 3.x oneOf and anyOf cases with that alternative, including basic-type unions. Done means the generator produces usable models for these constructs rather than empty interfaces or classes.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.