Fix ProducesResponseType's Description not being set for Minimal API's when attribute and inferred types aren't an exact match

src/Mvc/Mvc.ApiExplorer/src/EndpointMetadataApiDescriptionProvider.cs

@@ -322,6 +322,7 @@
         Type returnType,
         EndpointMetadataCollection endpointMetadata)
     {
+        System.Diagnostics.Debugger.Break();
         var responseType = returnType;
 
         // We support attributes (which implement the IApiResponseMetadataProvider) interface
@@ -404,15 +405,28 @@
             string? matchingDescription = null;
             foreach (var metadata in responseMetadataTypes)
             {
                 if (metadata.StatusCode == apiResponseType.StatusCode &&
-                    metadata.Type == apiResponseType.Type &&
+                    TypesAreCompatible(apiResponseType?.Type, metadata?.Type) &&
                     metadata.Description is not null)
                 {
                     matchingDescription = metadata.Description;
                 }
             }
             return matchingDescription;
         }
+
+        static bool TypesAreCompatible(Type? apiResponseType, Type? metadaType)
+        {
+            // We need to a special check for cases where the inferred type is different than the one specified in attributes.
+            // For example, an endpoint that defines [ProducesResponseType<IEnumerable<WeatherForecast>>],
+            // but the endpoint returns weatherForecasts.ToList(). Because List<> is a different type than IEnumerable<>, it would incorrectly return false.
+            // Currently, we do a "simple" biderectional check to see if the types are assignable to each other.
+            // This isn't very thorough, but it works for most cases.
+            // For more information, check the related bug: https://github.com/dotnet/aspnetcore/issues/60518
+            return apiResponseType == metadaType ||
+                metadaType?.IsAssignableFrom(apiResponseType) == true ||
+                apiResponseType?.IsAssignableFrom(metadaType) == true;
+        }
     }
 
     private static ApiResponseType CreateDefaultApiResponseType(Type responseType)

src/Mvc/Mvc.ApiExplorer/test/EndpointMetadataApiDescriptionProviderTest.cs

@@ -331,6 +331,82 @@ public void AddsResponseDescription()
         Assert.Equal(expectedBadRequestDescription, badRequestResponseType.Description);
     }
 
+    [Fact]
+    public void AddsResponseDescription_WorksWithGenerics()
+    {
+        const string expectedOkDescription = "The weather forecast for the next 5 days.";
+
+        var apiDescription = GetApiDescription([ProducesResponseType<GenericClass<TimeSpan>>(StatusCodes.Status200OK, Description = "The weather forecast for the next 5 days.")]
+        () => new GenericClass<TimeSpan> { Value = new TimeSpan() });
+
+        var okResponseType = Assert.Single(apiDescription.SupportedResponseTypes);
+
+        Assert.Equal(200, okResponseType.StatusCode);
+        Assert.Equal(typeof(GenericClass<TimeSpan>), okResponseType.Type);
+        Assert.Equal(typeof(GenericClass<TimeSpan>), okResponseType.ModelMetadata?.ModelType);
+        Assert.Equal(expectedOkDescription, okResponseType.Description);
+
+        var createdOkFormat = Assert.Single(okResponseType.ApiResponseFormats);
+        Assert.Equal("application/json", createdOkFormat.MediaType);
+    }
+
+    [Fact]
+    public void AddsResponseDescription_WorksWithGenericsAndTypedResults()
+    {
+        const string expectedOkDescription = "The weather forecast for the next 5 days.";
+
+        var apiDescription = GetApiDescription([ProducesResponseType<GenericClass<TimeSpan>>(StatusCodes.Status200OK, Description = "The weather forecast for the next 5 days.")]
+        () => TypedResults.Ok(new GenericClass<TimeSpan> { Value = new TimeSpan() }));
+
+        var okResponseType = Assert.Single(apiDescription.SupportedResponseTypes);
+
+        Assert.Equal(200, okResponseType.StatusCode);
+        Assert.Equal(typeof(GenericClass<TimeSpan>), okResponseType.Type);
+        Assert.Equal(typeof(GenericClass<TimeSpan>), okResponseType.ModelMetadata?.ModelType);
+        Assert.Equal(expectedOkDescription, okResponseType.Description);
+
+        var createdOkFormat = Assert.Single(okResponseType.ApiResponseFormats);
+        Assert.Equal("application/json", createdOkFormat.MediaType);
+    }
+
+    [Fact]
+    public void AddsResponseDescription_WorksWithCollections()
+    {
+        const string expectedOkDescription = "The weather forecast for the next 5 days.";
+
+        var apiDescription = GetApiDescription([ProducesResponseType<IEnumerable<TimeSpan>>(StatusCodes.Status200OK, Description = "The weather forecast for the next 5 days.")]
+        () => new List<TimeSpan> { new() });
+
+        var okResponseType = Assert.Single(apiDescription.SupportedResponseTypes);
+
+        Assert.Equal(200, okResponseType.StatusCode);
+        Assert.Equal(typeof(List<TimeSpan>), okResponseType.Type); // We use List as the inferred type has higher priority than those set by metadata (attributes)
+        Assert.Equal(typeof(List<TimeSpan>), okResponseType.ModelMetadata?.ModelType);
+        Assert.Equal(expectedOkDescription, okResponseType.Description);
+
+        var createdOkFormat = Assert.Single(okResponseType.ApiResponseFormats);
+        Assert.Equal("application/json", createdOkFormat.MediaType);
+    }
+
+    [Fact]
+    public void AddsResponseDescription_WorksWithCollectionsAndTypedResults()
+    {
+        const string expectedOkDescription = "The weather forecast for the next 5 days.";
+
+        var apiDescription = GetApiDescription([ProducesResponseType<IEnumerable<TimeSpan>>(StatusCodes.Status200OK, Description = "The weather forecast for the next 5 days.")]
+        () => TypedResults.Ok(new List<TimeSpan> { new() }));
+
+        var okResponseType = Assert.Single(apiDescription.SupportedResponseTypes);
+
+        Assert.Equal(200, okResponseType.StatusCode);
+        Assert.Equal(typeof(List<TimeSpan>), okResponseType.Type); // We use List as the inferred type has higher priority than those set by metadata (attributes)
+        Assert.Equal(typeof(List<TimeSpan>), okResponseType.ModelMetadata?.ModelType);
+        Assert.Equal(expectedOkDescription, okResponseType.Description);
+
+        var createdOkFormat = Assert.Single(okResponseType.ApiResponseFormats);
+        Assert.Equal("application/json", createdOkFormat.MediaType);
+    }
+
     [Fact]
     public void WithEmptyMethodBody_AddsResponseDescription()
     {
@@ -1813,5 +1889,7 @@ private class TestServiceProvider : IServiceProvider
 
             return null;
         }
+
     }
+    private class GenericClass<TType> { public required TType Value { get; set; } }
 }