Preserve examples in v2 files and write them out as extensions

Author: MaggieKimani1

src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -3,7 +3,7 @@
 
 using System;
 using System.Collections.Generic;
-using System.Text.Json;
+using System.Linq;
 using Json.Schema;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Extensions;
@@ -433,6 +433,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

@@ -186,6 +186,7 @@ internal OpenApiBodyParameter ConvertToBodyParameter()
                 // To allow round-tripping we use an extension to hold the name
                 Name = "body",
                 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.
             };
@@ -219,6 +220,7 @@ internal IEnumerable<OpenApiFormDataParameter> ConvertToFormDataParameters()
                     Description = property.Value.GetDescription(),
                     Name = property.Key,
                     Schema = property.Value,
+                    Examples = Content.Values.FirstOrDefault()?.Examples,
                     Required = Content.First().Value.Schema.GetRequired()?.Contains(property.Key) ?? false
                 };
             }

src/Microsoft.OpenApi/Models/OpenApiResponse.cs

@@ -6,7 +6,9 @@
 using System.Linq;
 using System.Text.Json;
 using System.Text.Json.Nodes;
+using System.Xml.Linq;
 using Json.More;
+using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Helpers;
 using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Writers;
@@ -235,6 +237,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

@@ -4,6 +4,7 @@
 using System;
 using System.Collections.Generic;
 using Json.Schema;
+using Microsoft.OpenApi.Models;
 
 namespace Microsoft.OpenApi.Writers
 {
@@ -96,5 +97,13 @@ public interface IOpenApiWriter
         /// <param name="writer"></param>
         /// <param name="reference"></param>
         void WriteJsonSchemaReference(IOpenApiWriter writer, Uri reference);
+
+        /// <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

@@ -594,6 +594,29 @@ public void WriteJsonSchemaReference(IOpenApiWriter writer, Uri reference)
             this.WriteProperty(OpenApiConstants.DollarRef, reference.OriginalString);
             WriteEndObject();
         }
+
+        /// <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();
+        }
     }
 
     internal class FindJsonSchemaRefs : OpenApiVisitorBase