Add deserialization support for $self in V31 and V32 deserializers and move tests to OpenApiDocumentTests

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

Author: Copilot

src/Microsoft.OpenApi/Reader/V31/OpenApiDocumentDeserializer.cs

@@ -30,7 +30,21 @@ internal static partial class OpenApiV31Deserializer
         private static readonly PatternFieldMap<OpenApiDocument> _openApiPatternFields = new()
         {
             // We have no semantics to verify X- nodes, therefore treat them as just values.
-            {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.AddExtension(p, LoadExtension(p, n))}
+            {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => 
+            {
+                if (p.Equals("x-oai-$self", StringComparison.OrdinalIgnoreCase))
+                {
+                    var value = n.GetScalarValue();
+                    if (value != null && Uri.TryCreate(value, UriKind.Absolute, out var self))
+                    {
+                        o.Self = self;
+                    }
+                }
+                else
+                {
+                    o.AddExtension(p, LoadExtension(p, n));
+                }
+            }}
         };
 
         public static OpenApiDocument LoadOpenApi(RootNode rootNode, Uri location)

src/Microsoft.OpenApi/Reader/V32/OpenApiDocumentDeserializer.cs

@@ -18,6 +18,7 @@ internal static partial class OpenApiV32Deserializer
             },
             {"info", (o, n, _) => o.Info = LoadInfo(n, o)},
             {"jsonSchemaDialect", (o, n, _) => { if (n.GetScalarValue() is string {} sjsd && Uri.TryCreate(sjsd, UriKind.Absolute, out var jsd)) {o.JsonSchemaDialect = jsd;}} },
+            {"$self", (o, n, _) => { if (n.GetScalarValue() is string {} sself && Uri.TryCreate(sself, UriKind.Absolute, out var self)) {o.Self = self;}} },
             {"servers", (o, n, _) => o.Servers = n.CreateList(LoadServer, o)},
             {"paths", (o, n, _) => o.Paths = LoadPaths(n, o)},
             {"webhooks", (o, n, _) => o.Webhooks = n.CreateMap(LoadPathItem, o)},

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

@@ -2282,5 +2282,89 @@ public async Task SerializeDocWithEmptyOperationSecurityWorks()
             Assert.NotNull(actualOperation.Security);
             Assert.Empty(actualOperation.Security);
         }
+
+        [Fact]
+        public async Task SerializeDocumentWithSelfPropertyAsV32Works()
+        {
+            // Arrange
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo
+                {
+                    Title = "Self Property Test",
+                    Version = "1.0.0"
+                },
+                Self = new Uri("https://example.org/api/openapi.json")
+            };
+
+            var expected = @"openapi: '3.2.0'
+$self: https://example.org/api/openapi.json
+info:
+  title: Self Property Test
+  version: 1.0.0
+paths: { }";
+
+            // Act
+            var actual = await doc.SerializeAsYamlAsync(OpenApiSpecVersion.OpenApi3_2);
+
+            // Assert
+            Assert.Equal(expected.MakeLineBreaksEnvironmentNeutral(), actual.MakeLineBreaksEnvironmentNeutral());
+        }
+
+        [Fact]
+        public async Task SerializeDocumentWithSelfPropertyAsV31WritesAsExtension()
+        {
+            // Arrange
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo
+                {
+                    Title = "Self Property Test",
+                    Version = "1.0.0"
+                },
+                Self = new Uri("https://example.org/api/openapi.json")
+            };
+
+            var expected = @"openapi: '3.1.2'
+info:
+  title: Self Property Test
+  version: 1.0.0
+paths: { }
+x-oai-$self: https://example.org/api/openapi.json";
+
+            // Act
+            var actual = await doc.SerializeAsYamlAsync(OpenApiSpecVersion.OpenApi3_1);
+
+            // Assert
+            Assert.Equal(expected.MakeLineBreaksEnvironmentNeutral(), actual.MakeLineBreaksEnvironmentNeutral());
+        }
+
+        [Fact]
+        public async Task SerializeDocumentWithSelfPropertyAsV30WritesAsExtension()
+        {
+            // Arrange
+            var doc = new OpenApiDocument
+            {
+                Info = new OpenApiInfo
+                {
+                    Title = "Self Property Test",
+                    Version = "1.0.0"
+                },
+                Self = new Uri("https://example.org/api/openapi.json")
+            };
+
+            var expected = @"openapi: 3.0.4
+info:
+  title: Self Property Test
+  version: 1.0.0
+paths: { }
+x-oai-$self: https://example.org/api/openapi.json";
+
+            // Act
+            var actual = await doc.SerializeAsYamlAsync(OpenApiSpecVersion.OpenApi3_0);
+
+            // Assert
+            Assert.Equal(expected.MakeLineBreaksEnvironmentNeutral(), actual.MakeLineBreaksEnvironmentNeutral());
+        }
     }
 }