WIP: Better support for open generic when mapping types

[harvzor]

Issues

This helps with these issues:

• Support recursive type mappings #1810
• Support custom mappings on open generic types #1600
• Access DataContract and CLR Type in Open Generic Mapping #2333
• How to map Optional<T> #2359
• and probably more

The problem

The issue I'm trying to solve is that there's no way to generically solve all mappings for a type that uses open generics. We can currently do something like this:

services.AddSwaggerGen(c =>
{
    c.MapType(typeof(GenericType<string>), () => new OpenApiSchema { Type = "string" });
    c.MapType(typeof(GenericType<int>), () => new OpenApiSchema { Type = "number" });
    // and handle every other type that GenericType could be...
}

But writing an exhaustive list is impossible, especially when you need to support custom objects.

The solution

Provide the user with a MappingContext so they can dynamically handle different types:

c.MapType(typeof(GenericType<>), mappingContext =>
{
    var type = mappingContext.UnderlyingType.GenericTypeArguments[0];

    return mappingContext.SchemaGenerator.GenerateSchema(type, mappingContext.SchemaRepository);
});

The MappingContext contains these useful properties:

public interface IMappingContext
{
    ISchemaGenerator SchemaGenerator { get; }
    SchemaRepository SchemaRepository { get; }
    Type UnderlyingType { get; }
}

[harvzor]

I've kept the old MapType extension methods so that existing usages of this method won't become broken as I'm now providing the MappingContext.

However, if anyone is using swaggerGenOptions.SchemaGeneratorOptions.CustomTypeMappings directly instead of these helper methods, they will need to update their code.

[harvzor]

Need to add docs for the MappingContext

[harvzor]

Not sure if this is the best place to put this

But it at least needs to be integration tested

[harvzor]

Add a test for more complex custom objects such as:

public class Foo
{
    public string Bar { get; set; }
}

[martincostello]

Thanks for contributing - if you'd like to continue with this pull request, please rebase against the default branch to pick up our new CI.