Merge pull request #2645 from desjoerd/fix/support-v2/gh-2629

feat: Add `type: "null"` downcasting when in oneOf and anyOf for OpenAPI v3

Author: desjoerd

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -438,23 +438,39 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
 
             // enum
             var enumValue = Enum is not { Count: > 0 }
-                && !string.IsNullOrEmpty(Const) 
+                && !string.IsNullOrEmpty(Const)
                 && version < OpenApiSpecVersion.OpenApi3_1
                 ? new List<JsonNode> { JsonValue.Create(Const)! }
                 : Enum;
             writer.WriteOptionalCollection(OpenApiConstants.Enum, enumValue, (nodeWriter, s) => nodeWriter.WriteAny(s));
 
+            // Handle oneOf/anyOf with null type for v3.0 downcast
+            IList<IOpenApiSchema>? effectiveOneOf = OneOf;
+            IList<IOpenApiSchema>? effectiveAnyOf = AnyOf;
+            bool hasNullInComposition = false;
+            JsonSchemaType? inferredType = null;
+
+            if (version == OpenApiSpecVersion.OpenApi3_0)
+            {
+                (effectiveOneOf, var inferredOneOf, var nullInOneOf) = ProcessCompositionForNull(OneOf);
+                hasNullInComposition |= nullInOneOf;
+                inferredType = inferredOneOf ?? inferredType;
+                (effectiveAnyOf, var inferredAnyOf, var nullInAnyOf) = ProcessCompositionForNull(AnyOf);
+                hasNullInComposition |= nullInAnyOf;
+                inferredType = inferredAnyOf ?? inferredType;
+            }
+
             // type
-            SerializeTypeProperty(writer, version);
+            SerializeTypeProperty(writer, version, inferredType);
 
             // allOf
             writer.WriteOptionalCollection(OpenApiConstants.AllOf, AllOf, callback);
 
             // anyOf
-            writer.WriteOptionalCollection(OpenApiConstants.AnyOf, AnyOf, callback);
+            writer.WriteOptionalCollection(OpenApiConstants.AnyOf, effectiveAnyOf, callback);
 
             // oneOf
-            writer.WriteOptionalCollection(OpenApiConstants.OneOf, OneOf, callback);
+            writer.WriteOptionalCollection(OpenApiConstants.OneOf, effectiveOneOf, callback);
 
             // not
             writer.WriteOptionalObject(OpenApiConstants.Not, Not, callback);
@@ -493,7 +509,7 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             // nullable
             if (version == OpenApiSpecVersion.OpenApi3_0)
             {
-                SerializeNullable(writer, version);
+                SerializeNullable(writer, version, hasNullInComposition);
             }
 
             // discriminator
@@ -766,14 +782,17 @@ private void SerializeAsV2(
             writer.WriteEndObject();
         }
 
-        private void SerializeTypeProperty(IOpenApiWriter writer, OpenApiSpecVersion version)
+        private void SerializeTypeProperty(IOpenApiWriter writer, OpenApiSpecVersion version, JsonSchemaType? inferredType = null)
         {
-            if (Type is null)
+            // Use original type or inferred type when the explicit type is not set
+            var typeToUse = Type ?? inferredType;
+
+            if (typeToUse is null)
             {
                 return;
             }
 
-            var unifiedType = IsNullable ? Type.Value | JsonSchemaType.Null : Type.Value;
+            var unifiedType = IsNullable ? typeToUse.Value | JsonSchemaType.Null : typeToUse.Value;
             var typeWithoutNull = unifiedType & ~JsonSchemaType.Null;
 
             switch (version)
@@ -804,8 +823,8 @@ private static bool HasMultipleTypes(JsonSchemaType schemaType)
         private static void WriteUnifiedSchemaType(JsonSchemaType type, IOpenApiWriter writer)
         {
             var array = (from JsonSchemaType flag in jsonSchemaTypeValues
-                        where type.HasFlag(flag)
-                        select flag.ToFirstIdentifier()).ToArray();
+                         where type.HasFlag(flag)
+                         select flag.ToFirstIdentifier()).ToArray();
             if (array.Length > 1)
             {
                 writer.WriteOptionalCollection(OpenApiConstants.Type, array, (w, s) =>
@@ -822,9 +841,9 @@ where type.HasFlag(flag)
             }
         }
 
-        private void SerializeNullable(IOpenApiWriter writer, OpenApiSpecVersion version)
+        private void SerializeNullable(IOpenApiWriter writer, OpenApiSpecVersion version, bool hasNullInComposition = false)
         {
-            if (IsNullable)
+            if (IsNullable || hasNullInComposition)
             {
                 switch (version)
                 {
@@ -838,6 +857,41 @@ private void SerializeNullable(IOpenApiWriter writer, OpenApiSpecVersion version
             }
         }
 
+        /// <summary>
+        /// Processes a composition (oneOf or anyOf) for null types, filtering out null schemas and inferring common type.
+        /// </summary>
+        /// <param name="composition">The list of schemas in the composition.</param>
+        /// <returns>A tuple with the effective list, inferred type, and whether null is present in composition.</returns>
+        private static (IList<IOpenApiSchema>? effective, JsonSchemaType? inferredType, bool hasNullInComposition)
+            ProcessCompositionForNull(IList<IOpenApiSchema>? composition)
+        {
+            if (composition is null || !composition.Any(static s => s.Type is JsonSchemaType.Null))
+            {
+                // Nothing to patch
+                return (composition, null, false);
+            }
+
+            var nonNullSchemas = composition
+                .Where(static s => s.Type is null or not JsonSchemaType.Null)
+                .ToList();
+
+            if (nonNullSchemas.Count > 0)
+            {
+                JsonSchemaType commonType = 0;
+
+                foreach (var schema in nonNullSchemas)
+                {
+                    commonType |= schema.Type.GetValueOrDefault() & ~JsonSchemaType.Null;
+                }
+
+                return (nonNullSchemas, commonType, true);
+            }
+            else
+            {
+                return (null, null, true);
+            }
+        }
+
 #if NET5_0_OR_GREATER
         private static readonly Array jsonSchemaTypeValues = System.Enum.GetValues<JsonSchemaType>();
 #else