Add an improved annotation for polymorphic use of `OneOf`

Is your feature request related to a problem?

Yes! 🙂

Currently the implementation of oneOf in Hot Chocolate doesn't offer any measurable convenience or even any degree of "polymorphism" as implied by the spec and much of the documentation.

From a GraphQL spec point of view, it's just a mutally exclusive assertion: That one out of a handful of fields is non-null.

When consuming oneOf functionality in Hot Chocolate, nothing is done to leverage the common interface and it's still up to the developer to figure out which of the numerous fields is non-null, thus requiring a small-but-gross amount of boilerplate.

(It's a little funny, the documentation has // Omitted code for brevity in the sections where the most of the actual benefit people expect with oneOf to happen.)

[OneOf]
public class PetInput
{
    public Cat? Cat { get; set; }
    public Dog? Dog { get; set; }
    public Fish? Fish { get; set; }
}

public class Cat : IPet {}
public class Dog : IPet {}
public class Fish : IPet {}

public class Mutation
{
    public Task<IPet> CreatePetAsync(PetInput input)
    {
        // This is what's being omitted for "brevity". Hot Chocolate can totally help avoid this kind of boilerplate code.
        var pet = input.Cat ?? input.Dog ?? input.Fish ?? throw new("Unreachable thanks to `oneOf`.");

        return pet;
    }
}

Overall, I think Hot Chocolate can be of more assistance to the developer when the desired use of oneOf is for polymorphism.

The solution you'd like

In polymorphic scenarios, declaring InputType should be considered unnecessary. Hot Chocolate shouldn't require me to author something like a PetInput, but instead should be generating that type for the client automatically.

Accepting that the current OneOf exists and could still be useful in other scenarios, Hot Chocolate should introduce something that behaves largely like a union type, but when used for input, performs the work necessary to marshal a value of the correct type to the mutation:

[PolymorphicOneOf]
public interface IPet
{
}

public class Cat : IPet {}
public class Dog : IPet {}
public class Fish : IPet {}

public class Mutation
{
    public Task<IPet> CreatePetAsync(IPet pet)
    {
        // No code needs to be omitted for brevity anymore, `pet` is an `IPet`, yay!
        return pet;
    }
}

Product

Hot Chocolate

Start with the OneOf input-object documentation linked in the issue and compare it with the PetInput, IPet, and CreatePetAsync examples. Define how a new annotation should generate the client-facing input type and marshal the selected concrete type to the mutation, then verify that the existing OneOf behavior remains available for other scenarios.