Omit null OpenAPI response descriptions (#3077)

* Initial plan

fix(openapi): omit null response descriptions

Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

* test(models): update response serialization expectation

Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Author: Copilot

src/Microsoft.OpenApi/Models/OpenApiResponse.cs

@@ -73,7 +73,7 @@ public virtual void SerializeAsV3(IOpenApiWriter writer)
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
 
-        private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version, 
+        private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version,
             Action<IOpenApiWriter, IOpenApiSerializable> callback)
         {
             Utils.CheckArgumentNull(writer);
@@ -87,7 +87,7 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             }
 
             // description
-            writer.WriteRequiredProperty(OpenApiConstants.Description, Description);
+            writer.WriteProperty(OpenApiConstants.Description, Description);
 
             // headers
             writer.WriteOptionalMap(OpenApiConstants.Headers, Headers, callback);
@@ -120,7 +120,7 @@ public virtual void SerializeAsV2(IOpenApiWriter writer)
             writer.WriteStartObject();
 
             // description
-            writer.WriteRequiredProperty(OpenApiConstants.Description, Description);
+            writer.WriteProperty(OpenApiConstants.Description, Description);
 
             var extensionsClone = Extensions is not null ? new Dictionary<string, IOpenApiExtension>(Extensions) : null;
 
@@ -177,7 +177,7 @@ public virtual void SerializeAsV2(IOpenApiWriter writer)
                             // so remove it from the cloned collection so we don't write it again.
                             extensionsClone?.Remove(key);
                         }
-                    }                    
+                    }
                 }
             }
 

test/Microsoft.OpenApi.Tests/Mocks/OpenApiResponseSerializationTests.cs

@@ -1,5 +1,7 @@
 using System.IO;
 using System.Net.Http;
+using System.Text.Json.Nodes;
+using System.Threading.Tasks;
 using Moq;
 using Xunit;
 
@@ -61,5 +63,25 @@ public void SerializeAsV3_DoesNotCallV31OrV2Serialization()
             _linkMock.Verify(l => l.SerializeAsV31(It.IsAny<IOpenApiWriter>()), Times.Never);
             _linkMock.Verify(l => l.SerializeAsV2(It.IsAny<IOpenApiWriter>()), Times.Never);
         }
+
+        [Theory]
+        [InlineData(OpenApiSpecVersion.OpenApi2_0)]
+        [InlineData(OpenApiSpecVersion.OpenApi3_0)]
+        [InlineData(OpenApiSpecVersion.OpenApi3_1)]
+        [InlineData(OpenApiSpecVersion.OpenApi3_2)]
+        public async Task SerializeResponseWithoutDescriptionAsJsonDoesNotWriteNullDescription(OpenApiSpecVersion specVersion)
+        {
+            // Arrange
+            var response = new OpenApiResponse();
+
+            // Act
+            var actual = await response.SerializeAsJsonAsync(specVersion, TestContext.Current.CancellationToken);
+
+            // Assert
+            var node = JsonNode.Parse(actual);
+            Assert.NotNull(node);
+            var responseObject = Assert.IsType<JsonObject>(node);
+            Assert.False(responseObject.ContainsKey(OpenApiConstants.Description));
+        }
     }
 }

test/Microsoft.OpenApi.Tests/Models/OpenApiOperationTests.cs

@@ -343,7 +343,6 @@ public async Task SerializeOperationWithBodyAsV3JsonWorks()
                       "$ref": "#/components/responses/response1"
                     },
                     "400": {
-                      "description": null,
                       "content": {
                         "application/json": {
                           "schema": {
@@ -416,7 +415,6 @@ public async Task SerializeAdvancedOperationWithTagAndSecurityAsV3JsonWorks()
                       "$ref": "#/components/responses/response1"
                     },
                     "400": {
-                      "description": null,
                       "content": {
                         "application/json": {
                           "schema": {
@@ -648,7 +646,6 @@ public async Task SerializeOperationWithBodyAsV2JsonWorks()
                       "$ref": "#/responses/response1"
                     },
                     "400": {
-                      "description": null,
                       "schema": {
                         "type": "number",
                         "maximum": 10,
@@ -718,7 +715,6 @@ public async Task SerializeAdvancedOperationWithTagAndSecurityAsV2JsonWorks()
                       "$ref": "#/responses/response1"
                     },
                     "400": {
-                      "description": null,
                       "schema": {
                         "type": "number",
                         "maximum": 10,

test/Microsoft.OpenApi.Tests/Models/OpenApiResponseTests.cs

@@ -193,9 +193,7 @@ public async Task SerializeBasicResponseWorks(
             string format)
         {
             // Arrange
-            var expected = format == OpenApiConstants.Json ? @"{
-  ""description"": null
-}" : @"description: null";
+            var expected = @"{ }";
 
             // Act
             var actual = await BasicResponse.SerializeAsync(version, format, TestContext.Current.CancellationToken);