Merge branch 'feat/oai-3-2-support' into feat/Add-support-defaultMapping

baywet · baywet · commit 29273c60f0b3 · 2025-09-30T16:45:01.000-04:00
Signed-off-by: Vincent Biret &lt;vibiret@microsoft.com&gt;
diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSecurityScheme.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSecurityScheme.cs
@@ -45,4 +45,10 @@ public interface IOpenApiSecurityScheme : IOpenApiDescribedElement, IOpenApiRead
     /// REQUIRED. OpenId Connect URL to discover OAuth2 configuration values.
     /// </summary>
     public Uri? OpenIdConnectUrl { get; }
+
+    /// <summary>
+    /// Specifies that a security scheme is deprecated and SHOULD be transitioned out of usage.
+    /// Note: This field is supported in OpenAPI 3.2.0+. For earlier versions, it will be serialized as x-oai-deprecated extension.
+    /// </summary>
+    public bool Deprecated { get; }
 }
diff --git a/src/Microsoft.OpenApi/Models/OpenApiConstants.cs b/src/Microsoft.OpenApi/Models/OpenApiConstants.cs
@@ -40,6 +40,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string JsonSchemaDialect = "jsonSchemaDialect";
 
+        /// <summary>
+        /// Field: $self
+        /// </summary>
+        public const string Self = "$self";
+
         /// <summary>
         /// Field: Webhooks
         /// </summary>
diff --git a/src/Microsoft.OpenApi/Models/OpenApiDocument.cs b/src/Microsoft.OpenApi/Models/OpenApiDocument.cs
@@ -40,6 +40,11 @@ public void RegisterComponents()
         /// </summary>
         public Uri? JsonSchemaDialect { get; set; }
 
+        /// <summary>
+        /// The URI identifying this document. This MUST be in the form of a URI. (OAI 3.2.0+)
+        /// </summary>
+        public Uri? Self { get; set; }
+
         /// <summary>
         /// An array of Server Objects, which provide connectivity information to a target server.
         /// </summary>
@@ -126,6 +131,7 @@ public OpenApiDocument(OpenApiDocument? document)
             Workspace = document?.Workspace != null ? new(document.Workspace) : null;
             Info = document?.Info != null ? new(document.Info) : new OpenApiInfo();
             JsonSchemaDialect = document?.JsonSchemaDialect ?? JsonSchemaDialect;
+            Self = document?.Self ?? Self;
             Servers = document?.Servers != null ? [.. document.Servers] : null;
             Paths = document?.Paths != null ? new(document.Paths) : [];
             Webhooks = document?.Webhooks != null ? new Dictionary<string, IOpenApiPathItem>(document.Webhooks) : null;
@@ -200,6 +206,12 @@ private void SerializeAsV3X(IOpenApiWriter writer, string versionString, OpenApi
             // jsonSchemaDialect
             writer.WriteProperty(OpenApiConstants.JsonSchemaDialect, JsonSchemaDialect?.ToString());
 
+            // $self - only for v3.2+
+            if (version >= OpenApiSpecVersion.OpenApi3_2)
+            {
+                writer.WriteProperty(OpenApiConstants.Self, Self?.ToString());
+            }
+
             SerializeInternal(writer, version, callback);
 
             // webhooks
@@ -218,6 +230,12 @@ private void SerializeAsV3X(IOpenApiWriter writer, string versionString, OpenApi
                 }
             });
 
+            // $self as extension for v3.1 and earlier
+            if (version < OpenApiSpecVersion.OpenApi3_2 && Self is not null)
+            {
+                writer.WriteProperty(OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.Self, Self.ToString());
+            }
+
             writer.WriteEndObject();
         }
 
@@ -233,6 +251,13 @@ public void SerializeAsV3(IOpenApiWriter writer)
             // openapi
             writer.WriteProperty(OpenApiConstants.OpenApi, "3.0.4");
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (w, element) => element.SerializeAsV3(w));
+
+            // $self as extension for v3.0
+            if (Self is not null)
+            {
+                writer.WriteProperty(OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.Self, Self.ToString());
+            }
+
             writer.WriteEndObject();
         }
 
diff --git a/src/Microsoft.OpenApi/Models/OpenApiSecurityScheme.cs b/src/Microsoft.OpenApi/Models/OpenApiSecurityScheme.cs
@@ -35,6 +35,9 @@ public class OpenApiSecurityScheme : IOpenApiExtensible, IOpenApiSecurityScheme
         /// <inheritdoc/>
         public Uri? OpenIdConnectUrl { get; set; }
 
+        /// <inheritdoc/>
+        public bool Deprecated { get; set; }
+
         /// <inheritdoc/>
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
 
@@ -57,6 +60,7 @@ internal OpenApiSecurityScheme(IOpenApiSecurityScheme securityScheme)
             BearerFormat = securityScheme.BearerFormat ?? BearerFormat;
             Flows = securityScheme.Flows != null ? new(securityScheme.Flows) : null;
             OpenIdConnectUrl = securityScheme.OpenIdConnectUrl != null ? new Uri(securityScheme.OpenIdConnectUrl.OriginalString, UriKind.RelativeOrAbsolute) : null;
+            Deprecated = securityScheme.Deprecated;
             Extensions = securityScheme.Extensions != null ? new Dictionary<string, IOpenApiExtension>(securityScheme.Extensions) : null;
         }
         /// <summary>
@@ -124,6 +128,19 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
                     break;
             }
 
+            // deprecated - serialize as native field for v3.2+ or as extension for earlier versions
+            if (Deprecated)
+            {
+                if (version >= OpenApiSpecVersion.OpenApi3_2)
+                {
+                    writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
+                }
+                else
+                {
+                    writer.WriteProperty("x-oai-deprecated", Deprecated, false);
+                }
+            }
+
             // extensions
             writer.WriteExtensions(Extensions, version);
 
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiSecuritySchemeReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiSecuritySchemeReference.cs
@@ -60,6 +60,9 @@ public string? Description
         /// <inheritdoc/>
         public SecuritySchemeType? Type { get => Target?.Type; }
 
+        /// <inheritdoc/>
+        public bool Deprecated { get => Target?.Deprecated ?? default; }
+
         /// <inheritdoc/>
         public override IOpenApiSecurityScheme CopyReferenceAsTargetElementWithOverrides(IOpenApiSecurityScheme source)
         {
diff --git a/src/Microsoft.OpenApi/Reader/V3/OpenApiDocumentDeserializer.cs b/src/Microsoft.OpenApi/Reader/V3/OpenApiDocumentDeserializer.cs
@@ -32,7 +32,21 @@ internal static partial class OpenApiV3Deserializer
         private static readonly PatternFieldMap<OpenApiDocument> _openApiPatternFields = new PatternFieldMap<OpenApiDocument>
         {
             // 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)
+                    {
+                        o.Self = new(value, UriKind.Absolute);
+                    }
+                }
+                else
+                {
+                    o.AddExtension(p, LoadExtension(p, n));
+                }
+            }}
         };
 
         public static OpenApiDocument LoadOpenApi(RootNode rootNode, Uri location)
diff --git a/src/Microsoft.OpenApi/Reader/V3/OpenApiSecuritySchemeDeserializer.cs b/src/Microsoft.OpenApi/Reader/V3/OpenApiSecuritySchemeDeserializer.cs
@@ -72,7 +72,21 @@ internal static partial class OpenApiV3Deserializer
         private static readonly PatternFieldMap<OpenApiSecurityScheme> _securitySchemePatternFields =
             new()
             {
-                {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-deprecated", StringComparison.OrdinalIgnoreCase))
+                    {
+                        var deprecated = n.GetScalarValue();
+                        if (deprecated != null)
+                        {
+                            o.Deprecated = bool.Parse(deprecated);
+                        }
+                    }
+                    else
+                    {
+                        o.AddExtension(p, LoadExtension(p,n));
+                    }
+                }}
             };
 
         public static IOpenApiSecurityScheme LoadSecurityScheme(ParseNode node, OpenApiDocument hostDocument)
diff --git a/src/Microsoft.OpenApi/Reader/V31/OpenApiDocumentDeserializer.cs b/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)
diff --git a/src/Microsoft.OpenApi/Reader/V31/OpenApiSecuritySchemeDeserializer.cs b/src/Microsoft.OpenApi/Reader/V31/OpenApiSecuritySchemeDeserializer.cs
@@ -79,7 +79,21 @@ internal static partial class OpenApiV31Deserializer
         private static readonly PatternFieldMap<OpenApiSecurityScheme> _securitySchemePatternFields =
             new()
             {
-                {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-deprecated", StringComparison.OrdinalIgnoreCase))
+                    {
+                        var deprecated = n.GetScalarValue();
+                        if (deprecated != null)
+                        {
+                            o.Deprecated = bool.Parse(deprecated);
+                        }
+                    }
+                    else
+                    {
+                        o.AddExtension(p, LoadExtension(p,n));
+                    }
+                }}
             };
 
         public static IOpenApiSecurityScheme LoadSecurityScheme(ParseNode node, OpenApiDocument hostDocument)
diff --git a/src/Microsoft.OpenApi/Reader/V32/OpenApiDocumentDeserializer.cs b/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)},
diff --git a/src/Microsoft.OpenApi/Reader/V32/OpenApiSecuritySchemeDeserializer.cs b/src/Microsoft.OpenApi/Reader/V32/OpenApiSecuritySchemeDeserializer.cs
@@ -73,6 +73,16 @@ internal static partial class OpenApiV32Deserializer
                     {
                         o.Flows = LoadOAuthFlows(n, t);
                     }
+                },
+                {
+                    "deprecated", (o, n, _) =>
+                    {
+                        var deprecated = n.GetScalarValue();
+                        if (deprecated != null)
+                        {
+                            o.Deprecated = bool.Parse(deprecated);
+                        }
+                    }
                 }
             };
 
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDocumentTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDocumentTests.cs
@@ -611,5 +611,24 @@ public async Task ValidateReferencedExampleInSchemaWorks()
             Assert.Empty(result.Diagnostic.Errors);
             Assert.Empty(result.Diagnostic.Warnings);            
         }
+
+        [Fact]
+        public async Task ParseDocumentWithSelfExtensionWorks()
+        {
+            // Arrange && Act
+            var path = Path.Combine(SampleFolderPath, "documentWithSelfExtension.yaml");
+            var result = await OpenApiDocument.LoadAsync(path, SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(result.Document);
+            Assert.NotNull(result.Document.Self);
+            Assert.Equal("https://example.org/api/openapi.yaml", result.Document.Self.ToString());
+            Assert.Equal("API with x-oai-$self extension", result.Document.Info.Title);
+            Assert.Equal("1.0.0", result.Document.Info.Version);
+            // The x-oai-$self extension should be moved to the Self property and not remain in extensions
+            Assert.Null(result.Document.Extensions);
+            Assert.Empty(result.Diagnostic.Errors);
+            Assert.Empty(result.Diagnostic.Warnings);
+        }
     }
 }
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiSecuritySchemeReferenceDeserializerTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiSecuritySchemeReferenceDeserializerTests.cs
@@ -38,4 +38,33 @@ public void ShouldDeserializeSecuritySchemeReferenceAnnotations()
         Assert.Equal("This is a security scheme reference", resultReference.Description);
         Assert.NotNull(resultReference.Target);
     }
+
+    [Fact]
+    public void ShouldDeserializeSecuritySchemeWithXOaiDeprecatedExtension()
+    {
+        var json =
+        """
+        {
+            "type": "apiKey",
+            "description": "This is a deprecated security scheme",
+            "name": "api_key",
+            "in": "header",
+            "x-oai-deprecated": true
+        }
+        """;
+
+        var hostDocument = new OpenApiDocument();
+        var jsonNode = JsonNode.Parse(json);
+        var parseNode = ParseNode.Create(new ParsingContext(new()), jsonNode);
+
+        var result = OpenApiV31Deserializer.LoadSecurityScheme(parseNode, hostDocument);
+
+        Assert.NotNull(result);
+        var resultScheme = Assert.IsType<OpenApiSecurityScheme>(result);
+
+        Assert.Equal(SecuritySchemeType.ApiKey, resultScheme.Type);
+        Assert.Equal("api_key", resultScheme.Name);
+        Assert.Equal(ParameterLocation.Header, resultScheme.In);
+        Assert.True(resultScheme.Deprecated);
+    }
 }
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiDocument/documentWithSelfExtension.yaml b/test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiDocument/documentWithSelfExtension.yaml
@@ -0,0 +1,12 @@
+openapi: 3.1.2
+info:
+  title: API with x-oai-$self extension
+  version: 1.0.0
+paths:
+  /test:
+    get:
+      summary: Test endpoint
+      responses:
+        '200':
+          description: Success
+x-oai-$self: https://example.org/api/openapi.yaml
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiDocumentTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiDocumentTests.cs
@@ -611,6 +611,40 @@ public async Task ValidateReferencedExampleInSchemaWorks()
             Assert.Empty(result.Diagnostic.Errors);
             Assert.Empty(result.Diagnostic.Warnings);            
         }
+
+        [Fact]
+        public async Task ParseDocumentWithSelfPropertyFromYamlWorks()
+        {
+            // Arrange && Act
+            var path = Path.Combine(SampleFolderPath, "documentWithSelfProperty.yaml");
+            var result = await OpenApiDocument.LoadAsync(path, SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(result.Document);
+            Assert.NotNull(result.Document.Self);
+            Assert.Equal("https://example.org/api/openapi.yaml", result.Document.Self.ToString());
+            Assert.Equal("API with $self property", result.Document.Info.Title);
+            Assert.Equal("1.0.0", result.Document.Info.Version);
+            Assert.Empty(result.Diagnostic.Errors);
+            Assert.Empty(result.Diagnostic.Warnings);
+        }
+
+        [Fact]
+        public async Task ParseDocumentWithSelfPropertyFromJsonWorks()
+        {
+            // Arrange && Act
+            var path = Path.Combine(SampleFolderPath, "documentWithSelfProperty.json");
+            var result = await OpenApiDocument.LoadAsync(path, SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(result.Document);
+            Assert.NotNull(result.Document.Self);
+            Assert.Equal("https://example.org/api/openapi.json", result.Document.Self.ToString());
+            Assert.Equal("API with $self property", result.Document.Info.Title);
+            Assert.Equal("1.0.0", result.Document.Info.Version);
+            Assert.Empty(result.Diagnostic.Errors);
+            Assert.Empty(result.Diagnostic.Warnings);
+        }
     }
 }
 
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiSecuritySchemeReferenceDeserializerTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiSecuritySchemeReferenceDeserializerTests.cs
@@ -38,5 +38,34 @@ public void ShouldDeserializeSecuritySchemeReferenceAnnotations()
         Assert.Equal("This is a security scheme reference", resultReference.Description);
         Assert.NotNull(resultReference.Target);
     }
+
+    [Fact]
+    public void ShouldDeserializeSecuritySchemeWithDeprecatedField()
+    {
+        var json =
+        """
+        {
+            "type": "apiKey",
+            "description": "This is a deprecated security scheme",
+            "name": "api_key",
+            "in": "header",
+            "deprecated": true
+        }
+        """;
+
+        var hostDocument = new OpenApiDocument();
+        var jsonNode = JsonNode.Parse(json);
+        var parseNode = ParseNode.Create(new ParsingContext(new()), jsonNode);
+
+        var result = OpenApiV32Deserializer.LoadSecurityScheme(parseNode, hostDocument);
+
+        Assert.NotNull(result);
+        var resultScheme = Assert.IsType<OpenApiSecurityScheme>(result);
+
+        Assert.Equal(SecuritySchemeType.ApiKey, resultScheme.Type);
+        Assert.Equal("api_key", resultScheme.Name);
+        Assert.Equal(ParameterLocation.Header, resultScheme.In);
+        Assert.True(resultScheme.Deprecated);
+    }
 }
 
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V32Tests/Samples/OpenApiDocument/documentWithSelfProperty.json b/test/Microsoft.OpenApi.Readers.Tests/V32Tests/Samples/OpenApiDocument/documentWithSelfProperty.json
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V32Tests/Samples/OpenApiDocument/documentWithSelfProperty.yaml b/test/Microsoft.OpenApi.Readers.Tests/V32Tests/Samples/OpenApiDocument/documentWithSelfProperty.yaml
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiSecuritySchemeTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiSecuritySchemeTests.cs
diff --git a/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt b/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt

Original file line number	Diff line number	Diff line change
`@@ -60,6 +60,9 @@ public string? Description`
`60`	`60`	`/// <inheritdoc/>`
`61`	`61`	`public SecuritySchemeType? Type { get => Target?.Type; }`
`62`	`62`
	`63`	`+ /// <inheritdoc/>`
	`64`	`+ public bool Deprecated { get => Target?.Deprecated ?? default; }`
	`65`	`+`
`63`	`66`	`/// <inheritdoc/>`
`64`	`67`	`public override IOpenApiSecurityScheme CopyReferenceAsTargetElementWithOverrides(IOpenApiSecurityScheme source)`
`65`	`68`	`{`