fix: serialize examples as extension in v2/v3

Author: baywet

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -805,6 +805,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string ExamplesExtension = "x-examples";
 
+        /// <summary>
+        /// Extension: x-jsonschema-examples
+        /// </summary>
+        public const string JsonSchemaExamplesExtension = "x-jsonschema-examples";
+
         /// <summary>
         /// Field: version3_0_0
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -746,6 +746,7 @@ private void WriteV3CompatibilityKeywords(IOpenApiWriter writer, Action<IOpenApi
             writer.WriteOptionalObject(OpenApiConstants.IfExtension, If, callback);
             writer.WriteOptionalObject(OpenApiConstants.ThenExtension, Then, callback);
             writer.WriteOptionalObject(OpenApiConstants.ElseExtension, Else, callback);
+            writer.WriteOptionalCollection(OpenApiConstants.JsonSchemaExamplesExtension, Examples, (nodeWriter, s) => nodeWriter.WriteAny(s));
         }
 
         internal void WriteAsItemsProperties(IOpenApiWriter writer)
@@ -990,6 +991,8 @@ private void SerializeAsV2(
                 writer.WriteOptionalMap(OpenApiConstants.PatternPropertiesExtension, PatternProperties, (w, s) => s.SerializeAsV2(w));
             }
 
+            writer.WriteOptionalCollection(OpenApiConstants.JsonSchemaExamplesExtension, Examples, (nodeWriter, s) => nodeWriter.WriteAny(s));
+
             // extensions
             writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
 

src/Microsoft.OpenApi/PublicAPI.Unshipped.txt

@@ -1 +1,2 @@
 #nullable enable
+const Microsoft.OpenApi.OpenApiConstants.JsonSchemaExamplesExtension = "x-jsonschema-examples" -> string!

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

@@ -1752,6 +1752,60 @@ public async Task SerializePatternPropertiesAsExtensionInEarlierVersions(OpenApi
             Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), JsonNode.Parse(actual)));
         }
 
+        [Theory]
+        [InlineData(OpenApiSpecVersion.OpenApi2_0)]
+        [InlineData(OpenApiSpecVersion.OpenApi3_0)]
+        public async Task SerializeExamplesAsExtensionInEarlierVersions(OpenApiSpecVersion version)
+        {
+            var expected = """
+                {
+                  "x-jsonschema-examples": [
+                    "example value",
+                    42
+                  ]
+                }
+                """;
+            var schema = new OpenApiSchema
+            {
+                Examples =
+                [
+                    JsonValue.Create("example value")!,
+                    JsonValue.Create(42)!
+                ]
+            };
+
+            var actual = await schema.SerializeAsJsonAsync(version);
+
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), JsonNode.Parse(actual)));
+        }
+
+        [Theory]
+        [InlineData(OpenApiSpecVersion.OpenApi3_1)]
+        [InlineData(OpenApiSpecVersion.OpenApi3_2)]
+        public async Task SerializeExamplesAsJsonSchemaKeywordInV31AndLater(OpenApiSpecVersion version)
+        {
+            var expected = """
+                {
+                  "examples": [
+                    "example value",
+                    42
+                  ]
+                }
+                """;
+            var schema = new OpenApiSchema
+            {
+                Examples =
+                [
+                    JsonValue.Create("example value")!,
+                    JsonValue.Create(42)!
+                ]
+            };
+
+            var actual = await schema.SerializeAsJsonAsync(version);
+
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), JsonNode.Parse(actual)));
+        }
+
         [Theory]
         [InlineData(OpenApiSpecVersion.OpenApi2_0)]
         [InlineData(OpenApiSpecVersion.OpenApi3_0)]