WIP: Better support for open generic when mapping types #2704

harvzor · 2023-09-08T13:50:42Z

Issues

This helps with these issues:

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 · 2023-09-08T14:02:36Z

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

+        /// <summary>
+        /// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema
+        /// </summary>
+        /// <param name="swaggerGenOptions"></param>
+        /// <param name="type">System type</param>
+        /// <param name="schemaFactory">A factory method that generates Schema's for the provided type</param>
+        public static void MapType(
+            this SwaggerGenOptions swaggerGenOptions,
+            Type type,
+            Func<MappingContext, OpenApiSchema> schemaFactory)
+        {
+            swaggerGenOptions.SchemaGeneratorOptions.CustomTypeMappings.Add(type, schemaFactory);
+        }
+
+        /// <summary>
+        /// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema
+        /// </summary>
+        /// <typeparam name="T">System type</typeparam>
+        /// <param name="swaggerGenOptions"></param>
+        /// <param name="schemaFactory">A factory method that generates Schema's for the provided type</param>
+        public static void MapType<T>(
+            this SwaggerGenOptions swaggerGenOptions,
+            Func<MappingContext, OpenApiSchema> schemaFactory)
+        {
+            swaggerGenOptions.MapType(typeof(T), schemaFactory);
+        }


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.

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/MappingContext.cs

...Swashbuckle.AspNetCore.SwaggerGen.Test/SchemaGenerator/JsonSerializerSchemaGeneratorTests.cs

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

harvzor · 2023-09-09T15:28:43Z

test/WebSites/Basic/Controllers/GenericsController.cs

+namespace Basic.Controllers
+{
+    /// <summary>
+    /// Summary for GenericsController
+    /// </summary>
+    [Route("/generics")]
+    [Produces("application/json")]
+    public class GenericsController
+    {
+        [HttpPost(Name = "CreateString")]
+        public string CreateString([FromBody] GenericType<string> genericString)
+        {
+            throw new NotImplementedException();
+        }
+
+        [HttpPost(Name = "CreateDateTime")]
+        public string CreateDateTime([FromBody] GenericType<DateTime> genericObject)
+        {
+            throw new NotImplementedException();
+        }
+    }
+}


Not sure if this is the best place to put this

But it at least needs to be integration tested

As long as a test would fail if this functionality got broken, it should be fine to live here. New projects are typically added when specific configurations are needed for the generation or for different types of apps.

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/MappingContext.cs

harvzor · 2023-09-09T15:30:41Z

test/WebSites/Basic/Controllers/GenericsController.cs

+            throw new NotImplementedException();
+        }
+    }
+}


Add a test for more complex custom objects such as:

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

test/WebSites/Basic/GenericTypes.cs

martincostello · 2024-04-13T08:25:58Z

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.

…ngContext.

harvzor · 2024-05-17T15:31:21Z

README.md

@@ -839,6 +839,26 @@ services.AddSwaggerGen(c =>
 };
 ```

+As of version v6.6.x, you can easily map generic types dynamically by accessing the underlying type at runtime. In this example, I want to treat `GenericType` as if it was the generic type `T`:


Need to make sure the version is correct when this is released

martincostello · 2024-05-17T15:35:08Z

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

@@ -195,6 +195,33 @@ public static void AddServer(this SwaggerGenOptions swaggerGenOptions, OpenApiSe
            swaggerGenOptions.MapType(typeof(T), schemaFactory);
        }

+        /// <summary>
+        /// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema


Unless "JSONSchema" is a specific term I've not heard before:

Suggested change

/// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema

/// Provides a custom mapping, for a given type, to the Swagger-flavored JSON schema

martincostello · 2024-05-17T15:35:31Z

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

+        /// </summary>
+        /// <param name="swaggerGenOptions"></param>
+        /// <param name="type">System type</param>
+        /// <param name="schemaFactory">A factory method that generates Schema's for the provided type</param>


Suggested change

/// <param name="schemaFactory">A factory method that generates Schema's for the provided type</param>

/// <param name="schemaFactory">A factory method that generates schemas for the provided type</param>

martincostello · 2024-05-17T15:36:09Z

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs

+        }
+
+        /// <summary>
+        /// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema


Suggested change

/// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema

/// Provides a custom mapping, for a given type, to the Swagger-flavored JSON schema

martincostello · 2024-05-17T15:38:02Z

src/Swashbuckle.AspNetCore.SwaggerGen/SchemaGenerator/SchemaGeneratorOptions.cs

            SchemaIdSelector = DefaultSchemaIdSelector;
            SubTypesSelector = DefaultSubTypesSelector;
            DiscriminatorNameSelector = DefaultDiscriminatorNameSelector;
            DiscriminatorValueSelector = DefaultDiscriminatorValueSelector;
            SchemaFilters = new List<ISchemaFilter>();
        }

-        public IDictionary<Type, Func<OpenApiSchema>> CustomTypeMappings { get; set; }
+        public IDictionary<Type, Func<MappingContext, OpenApiSchema>> CustomTypeMappings { get; set; }


This is a binary-breaking change, so if we took it as-is this would have to be part of v7.

This would get released sooner if there were a way to implement this without breaking changes.

martincostello · 2024-05-17T15:39:04Z

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/MappingContext.cs

+            UnderlyingType = underlyingType;
+        }
+
+        public readonly ISchemaGenerator SchemaGenerator;


Use properties, not fields.

martincostello · 2024-05-17T15:39:25Z

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/MappingContext.cs

+
+namespace Swashbuckle.AspNetCore.SwaggerGen
+{
+    public class MappingContext


This could be sealed.

martincostello · 2024-05-17T15:39:54Z

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/MappingContext.cs

+
+namespace Swashbuckle.AspNetCore.SwaggerGen
+{
+    public class MappingContext


Please /// document all the members as this is a new public-facing type.

martincostello · 2024-05-17T15:40:52Z

...Swashbuckle.AspNetCore.SwaggerGen.Test/SchemaGenerator/JsonSerializerSchemaGeneratorTests.cs

+                    if (genericTypeArgument == typeof(int))
+                        return new OpenApiSchema { Type = "number" };
+
+                    throw new NotImplementedException();


It would be better to fail with an assertion related to what unexpected value was received.

martincostello · 2024-05-17T15:42:31Z

test/WebSites/Basic/Controllers/GenericsController.cs

+namespace Basic.Controllers
+{
+    /// <summary>
+    /// Summary for GenericsController
+    /// </summary>
+    [Route("/generics")]
+    [Produces("application/json")]
+    public class GenericsController
+    {
+        [HttpPost(Name = "CreateString")]
+        public string CreateString([FromBody] GenericType<string> genericString)
+        {
+            throw new NotImplementedException();
+        }
+
+        [HttpPost(Name = "CreateDateTime")]
+        public string CreateDateTime([FromBody] GenericType<DateTime> genericObject)
+        {
+            throw new NotImplementedException();
+        }
+    }
+}


As long as a test would fail if this functionality got broken, it should be fine to live here. New projects are typically added when specific configurations are needed for the generation or for different types of apps.

martincostello · 2024-05-17T15:44:04Z

test/WebSites/Basic/Startup.cs

@@ -55,6 +56,13 @@ public void ConfigureServices(IServiceCollection services)
                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Basic.xml"));

                c.EnableAnnotations();
+
+                c.MapType(typeof(GenericType<>), mappingContext =>


Test a generic type with more than one type parameter?

harvzor changed the title ~~Better support for open generic when mapping types~~ WIP: Better support for open generic when mapping types Sep 8, 2023

harvzor commented Sep 8, 2023

View reviewed changes

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/MappingContext.cs Outdated Show resolved Hide resolved

harvzor commented Sep 8, 2023

View reviewed changes

...Swashbuckle.AspNetCore.SwaggerGen.Test/SchemaGenerator/JsonSerializerSchemaGeneratorTests.cs Outdated Show resolved Hide resolved

harvzor commented Sep 8, 2023

View reviewed changes

...Swashbuckle.AspNetCore.SwaggerGen.Test/SchemaGenerator/JsonSerializerSchemaGeneratorTests.cs Outdated Show resolved Hide resolved

harvzor mentioned this pull request Sep 8, 2023

How to map Optional<T> #2359

Open

harvzor commented Sep 9, 2023

View reviewed changes

src/Swashbuckle.AspNetCore.SwaggerGen/DependencyInjection/SwaggerGenOptionsExtensions.cs Outdated Show resolved Hide resolved

harvzor commented Sep 9, 2023

View reviewed changes

src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/MappingContext.cs Outdated Show resolved Hide resolved

harvzor commented Sep 9, 2023

View reviewed changes

test/WebSites/Basic/GenericTypes.cs Outdated Show resolved Hide resolved

harvzor closed this May 17, 2024

harvzor force-pushed the master branch from 4504457 to ecce973 Compare May 17, 2024 15:00

harvzor added 6 commits May 17, 2024 17:22

Add basic example of how types could be accessed when using MapType.

618c8cc

Gave access to a MappingContext so I can use the schema generator.

182fe99

Couple of small fixes.

0294b8f

Better name.

6ff5c45

Even better name.

ea2332a

Implement test to show that you can generate a schema using the Mappi…

902500e

…ngContext.

harvzor reopened this May 17, 2024

Better docs.

f513aa1

harvzor commented May 17, 2024

View reviewed changes

Add IMappingContext.

fb5e9bb

martincostello reviewed May 17, 2024

View reviewed changes

Fix issue with similar types needing different paths.

8662c63

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: Better support for open generic when mapping types #2704

WIP: Better support for open generic when mapping types #2704

harvzor commented Sep 8, 2023 •

edited

harvzor Sep 8, 2023

harvzor Sep 9, 2023

martincostello May 17, 2024

harvzor Sep 9, 2023

martincostello commented Apr 13, 2024

harvzor May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

martincostello May 17, 2024

	/// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema
	/// Provides a custom mapping, for a given type, to the Swagger-flavored JSON schema

	/// <param name="schemaFactory">A factory method that generates Schema's for the provided type</param>
	/// <param name="schemaFactory">A factory method that generates schemas for the provided type</param>

WIP: Better support for open generic when mapping types #2704

Are you sure you want to change the base?

WIP: Better support for open generic when mapping types #2704

Conversation

harvzor commented Sep 8, 2023 • edited

Issues

The problem

The solution

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martincostello commented Apr 13, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

harvzor commented Sep 8, 2023 •

edited