Improve handling of oneOf

[jmini]

With OAS3 it is possible to use oneOf.
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#schema-object

See one example in composed-oneof.yaml from the test suite.

We should discuss how we want to handle this.

In my opinion (for java) the Schema containing only oneOf entries should be an interface, and all model classes corresponding to the schema mentioned in the oneOf should implement this interface.

[jonschoning]

What should DefaultCodegen expose?

Currently DefaultCodegen simply exposes a simple string returnType, so we don't know what the possible values are. Although overriding fromOperation would give access to Map<String, Schema> schemas but not sure if implementations should use schemas directly or expect a certain field on DefaultCodegen to assist in determing the possible values.

openapi-generator/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultCodegen.java

Line 2165 in 23ad9f3

op.returnType = cm.datatype;

changing returnType would probably break a lot of templates, so maybe there is a way for a lang to opt-in to supporting `oneOf``

just some thoughts, no real preferences on this atm

[jmini]

Well I think that in Java, an interface should be created, because you have no way to express a Type Union: return type is ObjA or ObjB.

Yes we need to add this to the Codegen without breaking anything for existing templates.
I did not investigate yet, how this could be added.

[jonschoning]

For Java, what would the interface look like for composed-oneof.yaml from the test suite? (ObjA and ObjB have different properties, and in theory could.have no properties in common). Also is the realtype field going to be a requirement to make it work?

[jmini]

We have problem with names when schema are inlined (this should be addressed in #8).
Let call it CompObj.

---

The interface can be empty in my opinion. The idea is that in Java code, you need to check with instanceOf: With obj being a CompObj

if(obj instanceOf ObjA) {
...
} else if(obj instanceOf ObjB) {
...
}

In typescript you do not need CompObj you can work directly with Union Type: http://www.typescriptlang.org/docs/handbook/advanced-types.html#union-types

---

About the discriminator (realtype)... It is not mandatory to have it in ObjA and ObjB. I do not think that it should be defined in the interface, but it will be useful information for the serializer/deserializer.

[jonschoning]

ah, yes, an empty/marker interface + casting would work. The old-school way of doing tagged unions in langs that don't support them is to expose a struct with a discriminator/enum that identifies which field contains the data e.g.

(pseudo-code)
[struct]
{
   discriminator: Enum/Int
   objA: ObjA
   objB: ObjB
}

which is more static in that it avoids casting, but has downside of having to use the discriminator to get the right data. But I'm not involved enough with Java to know what the best practices for Java are.

The marker interface method may be a cleaner solution.

Also worth noting other tools like c# autorest I don't think support this currently.

[jmini]

I think we should published the necessary information in the Codegen layer, each template can implement in its own way (depending on the capabilities / language features)