Fix null examples not working (#3793)

Follow-up to #3788 to resolve #3784 correctly.

Author: jgarciadelanoceda

src/Shared/JsonExtensions.cs

@@ -1,5 +1,6 @@
 using System.Text.Json;
 using System.Text.Json.Nodes;
+using Microsoft.OpenApi;
 
 namespace Swashbuckle.AspNetCore;
 
@@ -15,6 +16,10 @@ internal static class JsonExtensions
 
     public static string ToJson(this JsonNode value)
     {
+        if (value.IsJsonNullSentinel())
+        {
+            return "null";
+        }
         var json = value.ToJsonString(Options);
 
 #if !NET9_0_OR_GREATER

src/Swashbuckle.AspNetCore.SwaggerGen/XmlComments/XmlCommentsExampleHelper.cs

@@ -19,7 +19,7 @@ public static JsonNode Create(
 
         if (isStringType)
         {
-            return string.Equals(exampleString, "null") ? null : JsonValue.Create(exampleString);
+            return string.Equals(exampleString, "null") ? JsonNullSentinel.JsonNull : JsonValue.Create(exampleString);
         }
 
         // HACK If the value is a string, but we can't detect it as one, then

test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/10_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt

@@ -801,8 +801,10 @@
             "description": "3-letter ISO country code",
             "required": true,
             "schema": {
-              "type": "string"
-            }
+              "type": "string",
+              "example": null
+            },
+            "example": null
           },
           {
             "name": "city",

test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/8_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt

@@ -801,8 +801,10 @@
             "description": "3-letter ISO country code",
             "required": true,
             "schema": {
-              "type": "string"
-            }
+              "type": "string",
+              "example": null
+            },
+            "example": null
           },
           {
             "name": "city",

test/Swashbuckle.AspNetCore.IntegrationTests/snapshots/9_0/VerifyTests.SwaggerEndpoint_ReturnsValidSwaggerJson_startupType=Basic.Startup_swaggerRequestUri=v1.verified.txt

@@ -801,8 +801,10 @@
             "description": "3-letter ISO country code",
             "required": true,
             "schema": {
-              "type": "string"
-            }
+              "type": "string",
+              "example": null
+            },
+            "example": null
           },
           {
             "name": "city",

test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsExampleHelperTests.cs

@@ -80,7 +80,8 @@ public void Create_Returns_Null_When_Type_String_And_Value_Null_String_Literal()
         var example = XmlCommentsExampleHelper.Create(
             schemaRepository, schema, "null");
 
-        Assert.Null(example);
+        Assert.NotNull(example);
+        Assert.Equal("null", example.ToJson());
     }
 
     [Fact]

test/Swashbuckle.AspNetCore.SwaggerGen.Test/XmlComments/XmlCommentsSchemaFilterTests.cs

@@ -76,8 +76,8 @@ public void Apply_SetsDescription_FromPropertySummaryTag(
         { typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.ObjectProperty), JsonSchemaTypes.Object, "{\n  \"prop1\": 1,\n  \"prop2\": \"foobar\"\n}" },
         { typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.StringPropertyWithUri), JsonSchemaTypes.String, "\"https://test.com/a?b=1\\u0026c=2\"" },
         { typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.StringPropertyWithUri), JsonSchemaTypes.String, "\"https://test.com/a?b=1\\u0026c=2\"" },
-        { typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.StringPropertyWithNullExample), JsonSchemaTypes.String, null },
-        { typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.StringPropertyWithNullExample), JsonSchemaTypes.String, null },
+        { typeof(XmlAnnotatedType), nameof(XmlAnnotatedType.StringPropertyWithNullExample), JsonSchemaTypes.String, "null" },
+        { typeof(XmlAnnotatedRecord), nameof(XmlAnnotatedRecord.StringPropertyWithNullExample), JsonSchemaTypes.String, "null" },
     };
 
     [Theory]

test/WebSites/Basic/Controllers/FromQueryParamsController.cs

@@ -12,17 +12,17 @@ public class FromQueryParamsController
     public IActionResult ValidateAddress([FromQuery] Address address)
     {
         Debug.Assert(address is not null);
-        return new NoContentResult(); 
+        return new NoContentResult();
     }
 
     [HttpGet("zip-codes/validate")]
     public IActionResult ValidateZipCodes(
-        [FromQuery]IEnumerable<string> zipCodes,
-        [FromQuery(Name = "search")] [Required] Dictionary<string, string> parameters)
+        [FromQuery] IEnumerable<string> zipCodes,
+        [FromQuery(Name = "search")][Required] Dictionary<string, string> parameters)
     {
         Debug.Assert(zipCodes is not null);
         Debug.Assert(parameters is not null);
-        return new NoContentResult(); 
+        return new NoContentResult();
     }
 }
 
@@ -31,6 +31,7 @@ public class Address
     /// <summary>
     /// 3-letter ISO country code
     /// </summary>
+    /// <example>null</example>
     [Required]
     public string Country { get; set; }