use one of behind a flag instead for nullable enums

Author: ItsVeryWindy

Directory.Build.props

@@ -40,7 +40,7 @@
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <UseArtifactsOutput>true</UseArtifactsOutput>
-    <VersionPrefix>8.1.4</VersionPrefix>
+    <VersionPrefix>8.2.0</VersionPrefix>
     <WarnOnPackingNonPackableProject>false</WarnOnPackingNonPackableProject>
   </PropertyGroup>
   <PropertyGroup Condition=" '$(GITHUB_ACTIONS)' != '' AND '$(DEPENDABOT_JOB_ID)' == '' ">

src/Swashbuckle.AspNetCore.Newtonsoft/SchemaGenerator/NewtonsoftDataContractResolver.cs

@@ -22,11 +22,13 @@ public DataContract GetDataContractForType(Type type)
                 jsonConverter: JsonConverterFunc);
         }
 
-        var jsonContract = _contractResolver.ResolveContract(effectiveType);
+        var jsonContract = _contractResolver.ResolveContract(type);
 
-        if (jsonContract is JsonPrimitiveContract && !jsonContract.UnderlyingType.IsEnum)
+        var effectiveUnderlyingType = Nullable.GetUnderlyingType(jsonContract.UnderlyingType) ?? jsonContract.UnderlyingType;
+
+        if (jsonContract is JsonPrimitiveContract && !effectiveUnderlyingType.IsEnum)
         {
-            if (!PrimitiveTypesAndFormats.TryGetValue(jsonContract.UnderlyingType, out var primitiveTypeAndFormat))
+            if (!PrimitiveTypesAndFormats.TryGetValue(effectiveUnderlyingType, out var primitiveTypeAndFormat))
             {
                 primitiveTypeAndFormat = Tuple.Create(DataType.String, (string)null);
             }
@@ -38,9 +40,9 @@ public DataContract GetDataContractForType(Type type)
                 jsonConverter: JsonConverterFunc);
         }
 
-        if (jsonContract is JsonPrimitiveContract && jsonContract.UnderlyingType.IsEnum)
+        if (jsonContract is JsonPrimitiveContract && effectiveUnderlyingType.IsEnum)
         {
-            var enumValues = jsonContract.UnderlyingType.GetEnumValues();
+            var enumValues = effectiveUnderlyingType.GetEnumValues();
 
             // Test to determine if the serializer will treat as string
             var serializeAsString = (enumValues.Length > 0) &&
@@ -52,7 +54,7 @@ public DataContract GetDataContractForType(Type type)
 
             var primitiveTypeAndFormat = serializeAsString
                 ? PrimitiveTypesAndFormats[typeof(string)]
-                : PrimitiveTypesAndFormats[jsonContract.UnderlyingType.GetEnumUnderlyingType()];
+                : PrimitiveTypesAndFormats[effectiveUnderlyingType.GetEnumUnderlyingType()];
 
             return DataContract.ForPrimitive(
                 underlyingType: jsonContract.UnderlyingType,

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

@@ -32,6 +32,7 @@ private static void DeepCopy(SchemaGeneratorOptions source, SchemaGeneratorOptio
         target.DiscriminatorNameSelector = source.DiscriminatorNameSelector;
         target.DiscriminatorValueSelector = source.DiscriminatorValueSelector;
         target.UseAllOfToExtendReferenceSchemas = source.UseAllOfToExtendReferenceSchemas;
+        target.UseOneOfForNullableEnums = source.UseOneOfForNullableEnums;
         target.SupportNonNullableReferenceTypes = source.SupportNonNullableReferenceTypes;
         target.NonNullableReferenceTypesAsRequired = source.NonNullableReferenceTypesAsRequired;
         target.SchemaFilters = [.. source.SchemaFilters];

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

@@ -299,6 +299,15 @@ public static void UseAllOfToExtendReferenceSchemas(this SwaggerGenOptions swagg
         swaggerGenOptions.SchemaGeneratorOptions.UseAllOfToExtendReferenceSchemas = true;
     }
 
+    /// <summary>
+    /// Extend enumeration schemas using the <c>oneOf</c> construct to allow <see langword="null"/> when referenced.
+    /// </summary>
+    /// <param name="swaggerGenOptions"></param>
+    public static void UseOneOfForNullableEnums(this SwaggerGenOptions swaggerGenOptions)
+    {
+        swaggerGenOptions.SchemaGeneratorOptions.UseOneOfForNullableEnums = true;
+    }
+
     /// <summary>
     /// Enable detection of non nullable reference types to set Nullable flag accordingly on schema properties
     /// </summary>

src/Swashbuckle.AspNetCore.SwaggerGen/PublicAPI/PublicAPI.Unshipped.txt

@@ -0,0 +1,3 @@
+static Microsoft.Extensions.DependencyInjection.SwaggerGenOptionsExtensions.UseOneOfForNullableEnums(this Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenOptions swaggerGenOptions) -> void
+Swashbuckle.AspNetCore.SwaggerGen.SchemaGeneratorOptions.UseOneOfForNullableEnums.get -> bool
+Swashbuckle.AspNetCore.SwaggerGen.SchemaGeneratorOptions.UseOneOfForNullableEnums.set -> void

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

@@ -49,7 +49,7 @@ public DataContract GetDataContractForType(Type type)
             primitiveTypeAndFormat = PrimitiveTypesAndFormats[exampleType];
 
             return DataContract.ForPrimitive(
-                underlyingType: effectiveType,
+                underlyingType: type,
                 dataType: primitiveTypeAndFormat.Item1,
                 dataFormat: primitiveTypeAndFormat.Item2,
                 jsonConverter: (value) => JsonConverterFunc(value, type));

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

@@ -54,6 +54,18 @@ private OpenApiSchema GenerateSchemaForMember(
         MemberInfo memberInfo,
         DataProperty dataProperty = null)
     {
+        if (dataProperty != null)
+        {
+            var customAttributes = memberInfo.GetInlineAndMetadataAttributes();
+
+            var requiredAttribute = customAttributes.OfType<RequiredAttribute>().FirstOrDefault();
+
+            if (!IsNullable(requiredAttribute, dataProperty, memberInfo))
+            {
+                modelType = Nullable.GetUnderlyingType(modelType) ?? modelType;
+            }
+        }
+
         var dataContract = GetDataContractFor(modelType);
 
         var schema = _generatorOptions.UseOneOfForPolymorphism && IsBaseTypeWithKnownTypesDefined(dataContract, out var knownTypesDataContracts)
@@ -143,6 +155,13 @@ private OpenApiSchema GenerateSchemaForParameter(
         ParameterInfo parameterInfo,
         ApiParameterRouteInfo routeInfo)
     {
+        var customAttributes = parameterInfo.GetCustomAttributes();
+
+        if (customAttributes.OfType<RequiredAttribute>().Any())
+        {
+            modelType = Nullable.GetUnderlyingType(modelType) ?? modelType;
+        }
+
         var dataContract = GetDataContractFor(modelType);
 
         var schema = _generatorOptions.UseOneOfForPolymorphism && IsBaseTypeWithKnownTypesDefined(dataContract, out var knownTypesDataContracts)
@@ -157,8 +176,6 @@ private OpenApiSchema GenerateSchemaForParameter(
 
         if (schema.Reference == null)
         {
-            var customAttributes = parameterInfo.GetCustomAttributes();
-
             var defaultValue = parameterInfo.HasDefaultValue
                 ? parameterInfo.DefaultValue
                 : customAttributes.OfType<DefaultValueAttribute>().FirstOrDefault()?.Value;
@@ -168,6 +185,11 @@ private OpenApiSchema GenerateSchemaForParameter(
                 schema.Default = GenerateDefaultValue(dataContract, modelType, defaultValue);
             }
 
+            if (Nullable.GetUnderlyingType(modelType) is not null)
+            {
+                schema.Nullable = true;
+            }
+
             schema.ApplyValidationAttributes(customAttributes);
             if (routeInfo != null)
             {
@@ -271,7 +293,7 @@ private OpenApiSchema GenerateConcreteSchema(DataContract dataContract, SchemaRe
             case DataType.Number:
             case DataType.String:
                 {
-                    schemaFactory = () => CreatePrimitiveSchema(dataContract);
+                    schemaFactory = () => CreatePrimitiveSchema(dataContract, schemaRepository);
                     returnAsReference = dataContract.UnderlyingType.IsEnum && !_generatorOptions.UseInlineDefinitionsForEnums;
                     break;
                 }
@@ -317,8 +339,35 @@ private bool TryGetCustomTypeMapping(Type modelType, out Func<OpenApiSchema> sch
             (modelType.IsConstructedGenericType && _generatorOptions.CustomTypeMappings.TryGetValue(modelType.GetGenericTypeDefinition(), out schemaFactory));
     }
 
-    private static OpenApiSchema CreatePrimitiveSchema(DataContract dataContract)
+    private OpenApiSchema CreatePrimitiveSchema(DataContract dataContract, SchemaRepository schemaRepository)
     {
+        var underlyingType = Nullable.GetUnderlyingType(dataContract.UnderlyingType) ?? dataContract.UnderlyingType;
+
+        if (underlyingType.IsEnum && dataContract.UnderlyingType != underlyingType)
+        {
+            var enumDataContract = GetDataContractFor(underlyingType);
+
+            var enumSchema = GenerateConcreteSchema(enumDataContract, schemaRepository);
+
+            if (_generatorOptions.UseInlineDefinitionsForEnums)
+            {
+                enumSchema.Enum.Add(null);
+                return enumSchema;
+            }
+
+            if (_generatorOptions.UseOneOfForNullableEnums)
+            {
+                enumSchema.OneOf =
+                [
+                    new OpenApiSchema { Reference = enumSchema.Reference },
+                    new OpenApiSchema { Enum = [null] }
+                ];
+                enumSchema.Reference = null;
+            }
+
+            return enumSchema;
+        }
+
         var schema = new OpenApiSchema
         {
             Type = FromDataType(dataContract.DataType),
@@ -338,8 +387,6 @@ private static OpenApiSchema CreatePrimitiveSchema(DataContract dataContract)
         }
 #pragma warning restore CS0618 // Type or member is obsolete
 
-        var underlyingType = dataContract.UnderlyingType;
-
         if (underlyingType.IsEnum)
         {
             var enumValues = underlyingType.GetEnumValues().Cast<object>();
@@ -451,7 +498,7 @@ private OpenApiSchema CreateObjectSchema(DataContract dataContract, SchemaReposi
                 continue;
             }
 
-            var memberType = dataProperty.MemberType;
+            var memberType = dataProperty.IsNullable ? dataProperty.MemberType : (Nullable.GetUnderlyingType(dataProperty.MemberType) ?? dataProperty.MemberType);
 
             schema.Properties[dataProperty.Name] = (dataProperty.MemberInfo != null)
                 ? GenerateSchemaForMember(memberType, schemaRepository, dataProperty.MemberInfo, dataProperty)

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

@@ -40,6 +40,11 @@ public SchemaGeneratorOptions()
 
     public IList<ISchemaFilter> SchemaFilters { get; set; }
 
+    /// <summary>
+    /// Gets or sets a value indicating whether to extend enumeration schemas using the <c>oneOf</c> construct to allow <see langword="null"/> when referenced.
+    /// </summary>
+    public bool UseOneOfForNullableEnums { get; set; }
+
     private string DefaultSchemaIdSelector(Type modelType)
     {
         if (!modelType.IsConstructedGenericType)

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

@@ -598,7 +598,7 @@ apiParameter.Type is not null &&
 
         var schema = (type != null)
             ? GenerateSchema(
-                type,
+                Nullable.GetUnderlyingType(type) ?? type,
                 schemaRepository,
                 apiParameter.PropertyInfo(),
                 apiParameter.ParameterInfo(),