Union types with common fields

Currently there’s no way in the api.json syntax to share common fields across all the model types of a Union: common fields need to be repeated in the definition of all model types. Then, the code generated consists always of an “empty” sealed base trait (/ interface) with all case classes that extend from it repeating all fields.

It’d be nice to have the ability to share fields across all the model types of a union and have the code generated with a shared base-trait/abstract class containing the common fields: this would make writing the code that handles these models much easier (avoid lots of type matching / casting when just need to access common fields).

Two possible ways of supporting this:

1. add a fields property to the union declaration in api.json and have code generators reading from that to generate the base trait / abstract class for all the union types;
2. leave api.json syntax as it is and have the generators checking for common fields (all union types are models and all have a subset of fields with same name and type) and generating a base trait/class with them when found.

[mbryzek]

related to https://github.com/apicollective/apibuilder/issues/441

I think the best path forward is to introduce a new top level entity named “interfaces” that would contain a list of fields.

Then you could add interfaces to each union type. Apidoc would then validate that each interface was in fact implemented by each of the types - allowing us to generate code with the interfaces applied (e.g. traits in scala).

The one option question is how to clearly indicate that a particular model should inherit the fields from an interface - do they get prepended? appended? simpler is to validate that the interface is in fact implemented but this doesn’t solve for the duplication in the spec.

[mbryzek]

implemented in https://github.com/apicollective/apibuilder/pull/826