Preserve examples in v2 files and write them out as extensions

Author: MaggieKimani1

src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System;
@@ -394,6 +394,20 @@ public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
                 }
             }
 
+            //examples
+            if (Examples != null && Examples.Any())
+            {
+                writer.WritePropertyName("x-examples");
+                writer.WriteStartObject();
+
+                foreach (var example in Examples)
+                {
+                    writer.WritePropertyName(example.Key);
+                    writer.WriteV2Examples(writer, example.Value, OpenApiSpecVersion.OpenApi2_0);
+                }
+                writer.WriteEndObject();
+            }
+
             // extensions
             writer.WriteExtensions(extensionsClone, OpenApiSpecVersion.OpenApi2_0);
 

src/Microsoft.OpenApi/Models/OpenApiRequestBody.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System;
@@ -152,7 +152,8 @@ internal OpenApiBodyParameter ConvertToBodyParameter()
                 // V2 spec actually allows the body to have custom name.
                 // To allow round-tripping we use an extension to hold the name
                 Name = "body",
-                Schema = Content.Values.FirstOrDefault()?.Schema ?? new OpenApiSchema(),
+                Schema = Content.Values.FirstOrDefault()?.Schema ?? new JsonSchemaBuilder().Build(),
+                Examples = Content.Values.FirstOrDefault()?.Examples,
                 Required = Required,
                 Extensions = Extensions.ToDictionary(static k => k.Key, static v => v.Value)  // Clone extensions so we can remove the x-bodyName extensions from the output V2 model.
             };
@@ -184,7 +185,8 @@ internal IEnumerable<OpenApiFormDataParameter> ConvertToFormDataParameters()
                     Description = property.Value.Description,
                     Name = property.Key,
                     Schema = property.Value,
-                    Required = Content.First().Value.Schema.Required.Contains(property.Key)
+                    Examples = Content.Values.FirstOrDefault()?.Examples,
+                    Required = Content.First().Value.Schema.GetRequired()?.Contains(property.Key) ?? false
                 };
             }
         }

src/Microsoft.OpenApi/Models/OpenApiResponse.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System.Collections.Generic;
@@ -201,6 +201,27 @@ public void SerializeAsV2WithoutReference(IOpenApiWriter writer)
                         writer.WriteEndObject();
                     }
 
+                    if (Content.Values.Any(m => m.Examples != null && m.Examples.Any()))
+                    {
+                        writer.WritePropertyName("x-examples");
+                        writer.WriteStartObject();
+
+                        foreach (var mediaTypePair in Content)
+                        {
+                            var examples = mediaTypePair.Value.Examples;
+                            if (examples != null && examples.Any())
+                            {
+                                foreach (var example in examples)
+                                {
+                                    writer.WritePropertyName(example.Key);
+                                    writer.WriteV2Examples(writer, example.Value, OpenApiSpecVersion.OpenApi2_0);
+                                }
+                            }
+                        }
+
+                        writer.WriteEndObject();
+                    }
+
                     writer.WriteExtensions(mediatype.Value.Extensions, OpenApiSpecVersion.OpenApi2_0);
 
                     foreach (var key in mediatype.Value.Extensions.Keys)

src/Microsoft.OpenApi/Writers/IOpenApiWriter.cs

@@ -1,6 +1,8 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using Microsoft.OpenApi.Models;
+
 namespace Microsoft.OpenApi.Writers
 {
     /// <summary>
@@ -72,5 +74,13 @@ public interface IOpenApiWriter
         /// Flush the writer.
         /// </summary>
         void Flush();
+
+        /// <summary>
+        /// Writes out existing examples in a mediatype object
+        /// </summary>
+        /// <param name="writer"></param>
+        /// <param name="example"></param>
+        /// <param name="version"></param>
+        void WriteV2Examples(IOpenApiWriter writer, OpenApiExample example, OpenApiSpecVersion version);
     }
 }

src/Microsoft.OpenApi/Writers/OpenApiWriterBase.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System;
@@ -405,5 +405,28 @@ protected void VerifyCanWritePropertyName(string name)
                     string.Format(SRResource.ObjectScopeNeededForPropertyNameWriting, name));
             }
         }
+
+        /// <inheritdoc/>
+        public void WriteV2Examples(IOpenApiWriter writer, OpenApiExample example, OpenApiSpecVersion version)
+        {
+            writer.WriteStartObject();
+
+            // summary
+            writer.WriteProperty(OpenApiConstants.Summary, example.Summary);
+
+            // description
+            writer.WriteProperty(OpenApiConstants.Description, example.Description);
+
+            // value
+            writer.WriteOptionalObject(OpenApiConstants.Value, example.Value, (w, v) => w.WriteAny(v));
+
+            // externalValue
+            writer.WriteProperty(OpenApiConstants.ExternalValue, example.ExternalValue);
+
+            // extensions
+            writer.WriteExtensions(example.Extensions, version);
+
+            writer.WriteEndObject();
+        }
     }
 }