Add Deprecated property to SecurityScheme with serialization/deserialization

Co-authored-by: baywet <[email protected]>

Author: Copilot

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; }
 }

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);
 

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)
         {

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)

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

@@ -73,13 +73,37 @@ internal static partial class OpenApiV31Deserializer
                     {
                         o.Flows = LoadOAuthFlows(n, t);
                     }
+                },
+                {
+                    "deprecated", (o, n, _) =>
+                    {
+                        var deprecated = n.GetScalarValue();
+                        if (deprecated != null)
+                        {
+                            o.Deprecated = bool.Parse(deprecated);
+                        }
+                    }
                 }
             };
 
         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)

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);
+                        }
+                    }
                 }
             };