discriminated decorator should also support models and inheritance scenarios

[baywet]

Clear and concise description of the problem

Discriminator is still the recommended decorator to use for models and inheritance scenarios.

Having two decorators to functionally do the same thing leads to a sub-part developer experience and creates confusion across the board.

Functionally speaking this

@discriminator("kind")
model Pet {
  name: string;
  weight?: float32;
}
model Cat extends Pet {
  kind: "cat";
  meow: int32;
}
model Dog extends Pet {
  kind: "dog";
  bark: string;
}

Is equivalent to that

@discriminated(#{ discriminatorPropertyName: "kind", envelope: "none"})
model Pet {
  name: string;
  weight?: float32;
}
model Cat extends Pet {
  kind: "cat";
  meow: int32;
}
model Dog extends Pet {
  kind: "dog";
  bark: string;
}

As we address this issue we also need to ensure that:

• the OpenAPI3 emitter supports those new scenarios for the discriminated decorator
• the OpenAPI3 import tool is updated to use the discriminated decorator where it used the discriminator
• public documentation is updated

Checklist

• [x] Follow our Code of Conduct
• [x] Read the docs.
• [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[markcowl]

@markcowl link to union extends design issue