fix: marks deprecated properties from the specification as obsolete

Author: baywet

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

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using System.Text.Json.Nodes;
 
 namespace Microsoft.OpenApi;
@@ -42,6 +43,7 @@ public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyE
     /// If style is used, and if behavior is n/a (cannot be serialized),
     /// the value of allowEmptyValue SHALL be ignored.
     /// </summary>
+    [Obsolete("Use of AllowEmptyValue is not recommended and it is likely to be removed in a later revision.")]
     public bool AllowEmptyValue { get; }
 
     /// <summary>

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

@@ -243,6 +243,7 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// You must use the <see cref="JsonNullSentinel.IsJsonNullSentinel(JsonNode?)"/> method to check whether Default was assigned a null value in the document.
     /// Assign <see cref="JsonNullSentinel.JsonNull"/> to use get null as a serialized value.
     /// </summary>
+    [Obsolete("Use Examples instead.")]
     public JsonNode? Example { get; }
 
     /// <summary>

src/Microsoft.OpenApi/Models/JsonSchemaReference.cs

@@ -8,6 +8,8 @@
 
 namespace Microsoft.OpenApi;
 
+#pragma warning disable CS0618
+
 /// <summary>
 /// Schema reference information that includes metadata annotations from JSON Schema 2020-12.
 /// This class extends OpenApiReference to provide schema-specific metadata override capabilities.
@@ -267,6 +269,7 @@ public string? Const
     /// A free-form property to include an example of an instance for this schema.
     /// Follow <see href="https://spec.openapis.org/oas/v3.1.1.html#schema-object">OpenAPI Schema Object definition</see>.
     /// </summary>
+    [Obsolete("Use Examples instead.")]
     public JsonNode? Example { get; set; }
 
     /// <summary>

src/Microsoft.OpenApi/Models/OpenApiParameter.cs

@@ -8,6 +8,7 @@
 
 namespace Microsoft.OpenApi
 {
+#pragma warning disable CS0618
     /// <summary>
     /// Parameter Object.
     /// </summary>
@@ -32,6 +33,7 @@ public class OpenApiParameter : IOpenApiExtensible, IOpenApiParameter
         public bool Deprecated { get; set; }
 
         /// <inheritdoc/>
+        [Obsolete("Use of AllowEmptyValue is not recommended and it is likely to be removed in a later revision.")]
         public bool AllowEmptyValue { get; set; }
 
         /// <inheritdoc/>

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -251,6 +251,7 @@ public string? Minimum
         public OpenApiDiscriminator? Discriminator { get; set; }
 
         /// <inheritdoc />
+        [Obsolete("Use Examples instead.")]
         public JsonNode? Example { get; set; }
 
         /// <inheritdoc />
@@ -959,7 +960,9 @@ private void SerializeAsV2(
             writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, s) => s.SerializeAsV2(w));
 
             // example
+#pragma warning disable CS0618
             writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, e) => w.WriteAny(e));
+#pragma warning restore CS0618
 
             // x-nullable extension
             SerializeNullable(writer, OpenApiSpecVersion.OpenApi2_0);

src/Microsoft.OpenApi/Models/OpenApiXml.cs

@@ -30,7 +30,7 @@ public class OpenApiXml : IOpenApiSerializable, IOpenApiExtensible
         /// Declares whether the property definition translates to an attribute instead of an element.
         /// Default value is false.
         /// </summary>
-        [Obsolete("Use NodeType property instead. This property will be removed in a future version.")]
+        [Obsolete("Use NodeType set to OpenApiXmlNodeType.Attribute instead. This property will be removed in a future version.")]
         internal bool Attribute
         {
             get
@@ -47,7 +47,7 @@ internal bool Attribute
         /// Signifies whether the array is wrapped.
         /// Default value is false.
         /// </summary>
-        [Obsolete("Use NodeType property instead. This property will be removed in a future version.")]
+        [Obsolete("Use NodeType set to OpenApiXmlNodeType.Element instead. This property will be removed in a future version.")]
         internal bool Wrapped
         {
             get

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

@@ -1,11 +1,13 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using System;
 using System.Collections.Generic;
 using System.Text.Json.Nodes;
 
 namespace Microsoft.OpenApi
 {
+#pragma warning disable CS0618
     /// <summary>
     /// Parameter Object Reference.
     /// </summary>
@@ -50,6 +52,7 @@ public string? Description
         public bool Deprecated { get => Target?.Deprecated ?? default; }
 
         /// <inheritdoc/>
+        [Obsolete("Use of AllowEmptyValue is not recommended and it is likely to be removed in a later revision.")]
         public bool AllowEmptyValue { get => Target?.AllowEmptyValue ?? default; }
 
         /// <inheritdoc/>

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

@@ -167,6 +167,7 @@ public bool WriteOnly
         /// <inheritdoc/>
         public OpenApiDiscriminator? Discriminator { get => Reference.Discriminator ?? Target?.Discriminator; set => Reference.Discriminator = value; }
         /// <inheritdoc/>
+        [Obsolete("Use Examples instead.")]
         public JsonNode? Example { get => Reference.Example ?? Target?.Example; set => Reference.Example = value; }
         /// <inheritdoc/>
         public IList<JsonNode>? Examples

src/Microsoft.OpenApi/Reader/V2/OpenApiParameterDeserializer.cs

@@ -7,6 +7,8 @@
 using System.Collections.Generic;
 using System.Globalization;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Reader.V2
 {
     /// <summary>

src/Microsoft.OpenApi/Reader/V2/OpenApiSchemaDeserializer.cs

@@ -8,6 +8,8 @@
 using System.Text.Json;
 using System.Text.Json.Nodes;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Reader.V2
 {
     /// <summary>