Use allOf to model nullable return types

Author: captainsafia

src/OpenApi/src/Extensions/JsonTypeInfoExtensions.cs

@@ -108,6 +108,12 @@ internal static string GetSchemaReferenceId(this Type type, JsonSerializerOption
             return $"{typeName}Of{propertyNames}";
         }
 
+        // Special handling for nullable value types
+        if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Nullable<>))
+        {
+            return type.GetGenericArguments()[0].GetSchemaReferenceId(options);
+        }
+
         // Special handling for generic types that are collections
         // Generic types become a concatenation of the generic type name and the type arguments
         if (type.IsGenericType)

src/OpenApi/src/Extensions/OpenApiSchemaExtensions.cs

@@ -0,0 +1,21 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.OpenApi;
+
+internal static class OpenApiSchemaExtensions
+{
+    private static readonly OpenApiSchema _nullSchema = new() { Type = JsonSchemaType.Null };
+
+    public static IOpenApiSchema CreateAllOfNullableWrapper(this IOpenApiSchema originalSchema)
+    {
+        return new OpenApiSchema
+        {
+            AllOf =
+            [
+                _nullSchema,
+                originalSchema
+            ]
+        };
+    }
+}

src/OpenApi/src/Extensions/TypeExtensions.cs

@@ -1,6 +1,11 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Linq;
+using System.Reflection;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Controllers;
+
 namespace Microsoft.AspNetCore.OpenApi;
 
 internal static class TypeExtensions
@@ -30,4 +35,39 @@ public static bool IsJsonPatchDocument(this Type type)
 
         return false;
     }
+
+    public static bool ShouldApplyNullableResponseSchema(this ApiResponseType apiResponseType, ApiDescription apiDescription)
+    {
+        // Get the MethodInfo from the ActionDescriptor
+        var responseType = apiResponseType.Type;
+        var methodInfo = apiDescription.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor
+            ? controllerActionDescriptor.MethodInfo
+            : apiDescription.ActionDescriptor.EndpointMetadata.OfType<MethodInfo>().SingleOrDefault();
+
+        if (methodInfo is null)
+        {
+            return false;
+        }
+
+        var returnType = methodInfo.ReturnType;
+        if (returnType.IsGenericType &&
+            (returnType.GetGenericTypeDefinition() == typeof(Task<>) || returnType.GetGenericTypeDefinition() == typeof(ValueTask<>)))
+        {
+            returnType = returnType.GetGenericArguments()[0];
+        }
+        if (returnType != responseType)
+        {
+            return false;
+        }
+
+        if (returnType.IsValueType)
+        {
+            return apiResponseType.ModelMetadata?.IsNullableValueType ?? false;
+        }
+
+        var nullabilityInfoContext = new NullabilityInfoContext();
+        var nullabilityInfo = nullabilityInfoContext.Create(methodInfo.ReturnParameter);
+
+        return nullabilityInfo.WriteState == NullabilityState.Nullable;
+    }
 }

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -423,7 +423,14 @@ private async Task<OpenApiResponse> GetResponseAsync(
             .Select(responseFormat => responseFormat.MediaType);
         foreach (var contentType in apiResponseFormatContentTypes)
         {
-            var schema = apiResponseType.Type is { } type ? await _componentService.GetOrCreateSchemaAsync(document, type, scopedServiceProvider, schemaTransformers, null, cancellationToken) : new OpenApiSchema();
+            IOpenApiSchema schema = new OpenApiSchema();
+            if (apiResponseType.Type is { } responseType)
+            {
+                schema = await _componentService.GetOrCreateSchemaAsync(document, responseType, scopedServiceProvider, schemaTransformers, null, cancellationToken);
+                schema = apiResponseType.ShouldApplyNullableResponseSchema(apiDescription)
+                    ? schema.CreateAllOfNullableWrapper()
+                    : schema;
+            }
             response.Content[contentType] = new OpenApiMediaType { Schema = schema };
         }
 

src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs

@@ -97,6 +97,21 @@ internal sealed class OpenApiSchemaService(
             schema.ApplyPrimitiveTypesAndFormats(context, createSchemaReferenceId);
             schema.ApplySchemaReferenceId(context, createSchemaReferenceId);
             schema.MapPolymorphismOptionsToDiscriminator(context, createSchemaReferenceId);
+            if (schema[OpenApiConstants.SchemaId] is { } schemaId && schema[OpenApiSchemaKeywords.TypeKeyword] is JsonArray typeArray)
+            {
+                // Remove null from union types when present
+                for (var i = typeArray.Count - 1; i >= 0; i--)
+                {
+                    if (typeArray[i]?.GetValue<string>() == "null")
+                    {
+                        typeArray.RemoveAt(i);
+                    }
+                }
+                if (typeArray.Count == 1)
+                {
+                    schema[OpenApiSchemaKeywords.TypeKeyword] = typeArray[0]?.GetValue<string>();
+                }
+            }
             if (context.PropertyInfo is { } jsonPropertyInfo)
             {
                 schema.ApplyNullabilityContextInfo(jsonPropertyInfo);

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Services/OpenApiSchemaService/OpenApiSchemaService.ResponseSchemas.cs

@@ -174,6 +174,114 @@ public async Task GetOpenApiResponse_HandlesNullablePocoResponse()
         builder.MapGet("/api", GetTodo);
 #nullable restore
 
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            var operation = document.Paths["/api"].Operations[HttpMethod.Get];
+            var responses = Assert.Single(operation.Responses);
+            var response = responses.Value;
+            Assert.True(response.Content.TryGetValue("application/json", out var mediaType));
+            var schema = mediaType.Schema;
+            Assert.NotNull(schema.AllOf);
+            Assert.Equal(2, schema.AllOf.Count);
+            // Check that the allOf consists of a nullable schema and the GetTodo schema
+            Assert.Collection(schema.AllOf,
+                item =>
+                {
+                    Assert.NotNull(item);
+                    Assert.Equal(JsonSchemaType.Null, item.Type);
+                },
+                item =>
+                {
+                    Assert.NotNull(item);
+                    Assert.Equal(JsonSchemaType.Object, item.Type);
+                    Assert.Collection(item.Properties,
+                        property =>
+                        {
+                            Assert.Equal("id", property.Key);
+                            Assert.Equal(JsonSchemaType.Integer, property.Value.Type);
+                            Assert.Equal("int32", property.Value.Format);
+                        },
+                        property =>
+                        {
+                            Assert.Equal("title", property.Key);
+                            Assert.Equal(JsonSchemaType.String | JsonSchemaType.Null, property.Value.Type);
+                        },
+                        property =>
+                        {
+                            Assert.Equal("completed", property.Key);
+                            Assert.Equal(JsonSchemaType.Boolean, property.Value.Type);
+                        },
+                        property =>
+                        {
+                            Assert.Equal("createdAt", property.Key);
+                            Assert.Equal(JsonSchemaType.String, property.Value.Type);
+                            Assert.Equal("date-time", property.Value.Format);
+                        });
+                });
+
+        });
+    }
+
+    [Fact]
+    public async Task GetOpenApiResponse_HandlesNullablePocoTaskResponse()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+#nullable enable
+        static Task<Todo?> GetTodoAsync() => Task.FromResult(Random.Shared.Next() < 0.5 ? new Todo(1, "Test Title", true, DateTime.Now) : null);
+        builder.MapGet("/api", GetTodoAsync);
+#nullable restore
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            var operation = document.Paths["/api"].Operations[HttpMethod.Get];
+            var responses = Assert.Single(operation.Responses);
+            var response = responses.Value;
+            Assert.True(response.Content.TryGetValue("application/json", out var mediaType));
+            var schema = mediaType.Schema;
+            Assert.Equal(JsonSchemaType.Object, schema.Type);
+            Assert.Collection(schema.Properties,
+                property =>
+                {
+                    Assert.Equal("id", property.Key);
+                    Assert.Equal(JsonSchemaType.Integer, property.Value.Type);
+                    Assert.Equal("int32", property.Value.Format);
+                },
+                property =>
+                {
+                    Assert.Equal("title", property.Key);
+                    Assert.Equal(JsonSchemaType.String | JsonSchemaType.Null, property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("completed", property.Key);
+                    Assert.Equal(JsonSchemaType.Boolean, property.Value.Type);
+                },
+                property =>
+                {
+                    Assert.Equal("createdAt", property.Key);
+                    Assert.Equal(JsonSchemaType.String, property.Value.Type);
+                    Assert.Equal("date-time", property.Value.Format);
+                });
+        });
+    }
+
+    [Fact]
+    public async Task GetOpenApiResponse_HandlesNullablePocoValueTaskResponse()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+#nullable enable
+        static ValueTask<Todo?> GetTodoValueTaskAsync() => ValueTask.FromResult(Random.Shared.Next() < 0.5 ? new Todo(1, "Test Title", true, DateTime.Now) : null);
+        builder.MapGet("/api", GetTodoValueTaskAsync);
+#nullable restore
+
         // Assert
         await VerifyOpenApiDocument(builder, document =>
         {
@@ -231,6 +339,95 @@ await VerifyOpenApiDocument(builder, document =>
         });
     }
 
+    [Fact]
+    public async Task GetOpenApiResponse_HandlesNullableValueTypeResponse()
+    {
+        // Arrange
+        var builder = CreateBuilder();
+
+        // Act
+#nullable enable
+        static Point? GetNullablePoint() => Random.Shared.Next() < 0.5 ? new Point { X = 10, Y = 20 } : null;
+        builder.MapGet("/api/nullable-point", GetNullablePoint);
+
+        static Coordinate? GetNullableCoordinate() => Random.Shared.Next() < 0.5 ? new Coordinate(1.5, 2.5) : null;
+        builder.MapGet("/api/nullable-coordinate", GetNullableCoordinate);
+#nullable restore
+
+        // Assert
+        await VerifyOpenApiDocument(builder, document =>
+        {
+            // Verify nullable Point response
+            var pointOperation = document.Paths["/api/nullable-point"].Operations[HttpMethod.Get];
+            var pointResponses = Assert.Single(pointOperation.Responses);
+            var pointResponse = pointResponses.Value;
+            Assert.True(pointResponse.Content.TryGetValue("application/json", out var pointMediaType));
+            var pointSchema = pointMediaType.Schema;
+            Assert.NotNull(pointSchema.AllOf);
+            Assert.Equal(2, pointSchema.AllOf.Count);
+            Assert.Collection(pointSchema.AllOf,
+                item =>
+                {
+                    Assert.NotNull(item);
+                    Assert.Equal(JsonSchemaType.Null, item.Type);
+                },
+                item =>
+                {
+                    Assert.NotNull(item);
+                    Assert.Equal(JsonSchemaType.Object, item.Type);
+                    Assert.Collection(item.Properties,
+                        property =>
+                        {
+                            Assert.Equal("x", property.Key);
+                            Assert.Equal(JsonSchemaType.Integer, property.Value.Type);
+                            Assert.Equal("int32", property.Value.Format);
+                        },
+                        property =>
+                        {
+                            Assert.Equal("y", property.Key);
+                            Assert.Equal(JsonSchemaType.Integer, property.Value.Type);
+                            Assert.Equal("int32", property.Value.Format);
+                        });
+                });
+
+            // Verify nullable Coordinate response
+            var coordinateOperation = document.Paths["/api/nullable-coordinate"].Operations[HttpMethod.Get];
+            var coordinateResponses = Assert.Single(coordinateOperation.Responses);
+            var coordinateResponse = coordinateResponses.Value;
+            Assert.True(coordinateResponse.Content.TryGetValue("application/json", out var coordinateMediaType));
+            var coordinateSchema = coordinateMediaType.Schema;
+            Assert.NotNull(coordinateSchema.AllOf);
+            Assert.Equal(2, coordinateSchema.AllOf.Count);
+            Assert.Collection(coordinateSchema.AllOf,
+                item =>
+                {
+                    Assert.NotNull(item);
+                    Assert.Equal(JsonSchemaType.Null, item.Type);
+                },
+                item =>
+                {
+                    Assert.NotNull(item);
+                    Assert.Equal(JsonSchemaType.Object, item.Type);
+                    Assert.Collection(item.Properties,
+                        property =>
+                        {
+                            Assert.Equal("latitude", property.Key);
+                            Assert.Equal(JsonSchemaType.Number, property.Value.Type);
+                            Assert.Equal("double", property.Value.Format);
+                        },
+                        property =>
+                        {
+                            Assert.Equal("longitude", property.Key);
+                            Assert.Equal(JsonSchemaType.Number, property.Value.Type);
+                            Assert.Equal("double", property.Value.Format);
+                        });
+                });
+
+            // Assert that Point and Coordinates are the only schemas defined at the top-level
+            Assert.Equal(["Coordinate", "Point"], [.. document.Components.Schemas.Keys]);
+        });
+    }
+
     [Fact]
     public async Task GetOpenApiResponse_HandlesInheritedTypeResponse()
     {
@@ -732,4 +929,22 @@ private class ClassWithObjectProperty
         [DefaultValue(32)]
         public object AnotherObject { get; set; }
     }
+
+    private struct Point
+    {
+        public int X { get; set; }
+        public int Y { get; set; }
+    }
+
+    private readonly struct Coordinate
+    {
+        public double Latitude { get; }
+        public double Longitude { get; }
+
+        public Coordinate(double latitude, double longitude)
+        {
+            Latitude = latitude;
+            Longitude = longitude;
+        }
+    }
 }