feat(securityscheme): introduce IOAuth2MetadataProvider for OAuth2 metadata URL support

Author: mdaneri

src/Microsoft.OpenApi/Models/Interfaces/IOAuth2MetadataProvider.cs

@@ -0,0 +1,17 @@
+using System;
+
+namespace Microsoft.OpenApi;
+
+/// <summary>
+/// TEMPORARY compatibility interface for accessing OAuth2 metadata URL support introduced for OpenAPI 3.2.
+/// This exists to avoid adding new members to <see cref="IOpenApiSecurityScheme"/> in a minor release, which is binary breaking for existing compiled consumers.
+/// </summary>
+// TODO: Remove this temporary interface and collapse this member into IOpenApiSecurityScheme in the next major version.
+public interface IOAuth2MetadataProvider
+{
+    /// <summary>
+    /// URL to the OAuth2 Authorization Server Metadata document (RFC 8414).
+    /// Note: This field is supported in OpenAPI 3.2.0+ only.
+    /// </summary>
+    public Uri? OAuth2MetadataUrl { get; }
+}

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSecurityScheme.cs

@@ -5,6 +5,15 @@ namespace Microsoft.OpenApi;
 /// <summary>
 /// Defines the base properties for the security scheme object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
+///
+/// To preserve binary compatibility in minor releases, properties introduced after this interface shipped may be exposed through temporary companion interfaces.
+/// For OAuth2 metadata URL support, cast to <see cref="IOAuth2MetadataProvider"/>:
+/// <code>
+/// if (securityScheme is IOAuth2MetadataProvider provider)
+/// {
+///     var oauth2MetadataUrl = provider.OAuth2MetadataUrl;
+/// }
+/// </code>
 /// </summary>
 public interface IOpenApiSecurityScheme : IOpenApiDescribedElement, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiSecurityScheme>, IOpenApiReferenceable
 {
@@ -46,12 +55,6 @@ public interface IOpenApiSecurityScheme : IOpenApiDescribedElement, IOpenApiRead
     /// </summary>
     public Uri? OpenIdConnectUrl { get; }
 
-    /// <summary>
-    /// URL to the OAuth2 Authorization Server Metadata document (RFC 8414).
-    /// Note: This field is supported in OpenAPI 3.2.0+ only.
-    /// </summary>
-    public Uri? OAuth2MetadataUrl { 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.

src/Microsoft.OpenApi/Models/OpenApiSecurityScheme.cs

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Security Scheme Object.
     /// </summary>
-    public class OpenApiSecurityScheme : IOpenApiExtensible, IOpenApiSecurityScheme
+    public class OpenApiSecurityScheme : IOpenApiExtensible, IOpenApiSecurityScheme, IOAuth2MetadataProvider
     {
         /// <inheritdoc/>
         public SecuritySchemeType? Type { get; set; }
@@ -63,7 +63,9 @@ 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;
-            OAuth2MetadataUrl = securityScheme.OAuth2MetadataUrl != null ? new Uri(securityScheme.OAuth2MetadataUrl.OriginalString, UriKind.RelativeOrAbsolute) : null;
+            OAuth2MetadataUrl = securityScheme is IOAuth2MetadataProvider oauth2MetadataProvider && oauth2MetadataProvider.OAuth2MetadataUrl != null
+                ? new Uri(oauth2MetadataProvider.OAuth2MetadataUrl.OriginalString, UriKind.RelativeOrAbsolute)
+                : null;
             Deprecated = securityScheme.Deprecated;
             Extensions = securityScheme.Extensions != null ? new Dictionary<string, IOpenApiExtension>(securityScheme.Extensions) : null;
         }

src/Microsoft.OpenApi/Models/References/OpenApiSecuritySchemeReference.cs

@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Security Scheme Object Reference.
     /// </summary>
-    public class OpenApiSecuritySchemeReference : BaseOpenApiReferenceHolder<OpenApiSecurityScheme, IOpenApiSecurityScheme, OpenApiReferenceWithDescription>, IOpenApiSecurityScheme
+    public class OpenApiSecuritySchemeReference : BaseOpenApiReferenceHolder<OpenApiSecurityScheme, IOpenApiSecurityScheme, OpenApiReferenceWithDescription>, IOpenApiSecurityScheme, IOAuth2MetadataProvider
     {
         /// <summary>
         /// Constructor initializing the reference object.
@@ -55,7 +55,7 @@ public string? Description
         public Uri? OpenIdConnectUrl { get => Target?.OpenIdConnectUrl; }
 
         /// <inheritdoc/>
-        public Uri? OAuth2MetadataUrl { get => Target?.OAuth2MetadataUrl; }
+        public Uri? OAuth2MetadataUrl { get => Target is IOAuth2MetadataProvider oauth2MetadataProvider ? oauth2MetadataProvider.OAuth2MetadataUrl : null; }
 
         /// <inheritdoc/>
         public IDictionary<string, IOpenApiExtension>? Extensions { get => Target?.Extensions; }

test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt

@@ -105,6 +105,10 @@ namespace Microsoft.OpenApi
     {
         System.Collections.Generic.IDictionary<string, object>? Metadata { get; set; }
     }
+    public interface IOAuth2MetadataProvider
+    {
+        System.Uri? OAuth2MetadataUrl { get; }
+    }
     public interface IOpenApiCallback : Microsoft.OpenApi.IOpenApiElement, Microsoft.OpenApi.IOpenApiReadOnlyExtensible, Microsoft.OpenApi.IOpenApiReferenceable, Microsoft.OpenApi.IOpenApiSerializable, Microsoft.OpenApi.IShallowCopyable<Microsoft.OpenApi.IOpenApiCallback>
     {
         System.Collections.Generic.Dictionary<Microsoft.OpenApi.RuntimeExpression, Microsoft.OpenApi.IOpenApiPathItem>? PathItems { get; }
@@ -288,7 +292,6 @@ namespace Microsoft.OpenApi
         Microsoft.OpenApi.OpenApiOAuthFlows? Flows { get; }
         Microsoft.OpenApi.ParameterLocation? In { get; }
         string? Name { get; }
-        System.Uri? OAuth2MetadataUrl { get; }
         System.Uri? OpenIdConnectUrl { get; }
         string? Scheme { get; }
         Microsoft.OpenApi.SecuritySchemeType? Type { get; }
@@ -1373,7 +1376,7 @@ namespace Microsoft.OpenApi
         public virtual void SerializeAsV31(Microsoft.OpenApi.IOpenApiWriter writer) { }
         public virtual void SerializeAsV32(Microsoft.OpenApi.IOpenApiWriter writer) { }
     }
-    public class OpenApiSecurityScheme : Microsoft.OpenApi.IOpenApiDescribedElement, Microsoft.OpenApi.IOpenApiElement, Microsoft.OpenApi.IOpenApiExtensible, Microsoft.OpenApi.IOpenApiReadOnlyExtensible, Microsoft.OpenApi.IOpenApiReferenceable, Microsoft.OpenApi.IOpenApiSecurityScheme, Microsoft.OpenApi.IOpenApiSerializable, Microsoft.OpenApi.IShallowCopyable<Microsoft.OpenApi.IOpenApiSecurityScheme>
+    public class OpenApiSecurityScheme : Microsoft.OpenApi.IOAuth2MetadataProvider, Microsoft.OpenApi.IOpenApiDescribedElement, Microsoft.OpenApi.IOpenApiElement, Microsoft.OpenApi.IOpenApiExtensible, Microsoft.OpenApi.IOpenApiReadOnlyExtensible, Microsoft.OpenApi.IOpenApiReferenceable, Microsoft.OpenApi.IOpenApiSecurityScheme, Microsoft.OpenApi.IOpenApiSerializable, Microsoft.OpenApi.IShallowCopyable<Microsoft.OpenApi.IOpenApiSecurityScheme>
     {
         public OpenApiSecurityScheme() { }
         public string? BearerFormat { get; set; }
@@ -1393,7 +1396,7 @@ namespace Microsoft.OpenApi
         public virtual void SerializeAsV31(Microsoft.OpenApi.IOpenApiWriter writer) { }
         public virtual void SerializeAsV32(Microsoft.OpenApi.IOpenApiWriter writer) { }
     }
-    public class OpenApiSecuritySchemeReference : Microsoft.OpenApi.BaseOpenApiReferenceHolder<Microsoft.OpenApi.OpenApiSecurityScheme, Microsoft.OpenApi.IOpenApiSecurityScheme, Microsoft.OpenApi.OpenApiReferenceWithDescription>, Microsoft.OpenApi.IOpenApiDescribedElement, Microsoft.OpenApi.IOpenApiElement, Microsoft.OpenApi.IOpenApiReadOnlyExtensible, Microsoft.OpenApi.IOpenApiReferenceable, Microsoft.OpenApi.IOpenApiSecurityScheme, Microsoft.OpenApi.IOpenApiSerializable, Microsoft.OpenApi.IShallowCopyable<Microsoft.OpenApi.IOpenApiSecurityScheme>
+    public class OpenApiSecuritySchemeReference : Microsoft.OpenApi.BaseOpenApiReferenceHolder<Microsoft.OpenApi.OpenApiSecurityScheme, Microsoft.OpenApi.IOpenApiSecurityScheme, Microsoft.OpenApi.OpenApiReferenceWithDescription>, Microsoft.OpenApi.IOAuth2MetadataProvider, Microsoft.OpenApi.IOpenApiDescribedElement, Microsoft.OpenApi.IOpenApiElement, Microsoft.OpenApi.IOpenApiReadOnlyExtensible, Microsoft.OpenApi.IOpenApiReferenceable, Microsoft.OpenApi.IOpenApiSecurityScheme, Microsoft.OpenApi.IOpenApiSerializable, Microsoft.OpenApi.IShallowCopyable<Microsoft.OpenApi.IOpenApiSecurityScheme>
     {
         public OpenApiSecuritySchemeReference(string referenceId, Microsoft.OpenApi.OpenApiDocument? hostDocument = null, string? externalResource = null) { }
         public string? BearerFormat { get; }