fix: marks deprecated properties from the specification as obsolete

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 @@
     /// 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 @@
     /// 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>
@@ -265,7 +266,7 @@
     /// <remarks>
     /// NOTE: This property differs from the naming pattern of AdditionalPropertiesAllowed for binary compatibility reasons.
     /// In the next major version, this will be renamed to UnevaluatedPropertiesAllowed.
     /// TODO: Rename to UnevaluatedPropertiesAllowed in the next major version.
     /// </remarks>
     public bool UnevaluatedProperties { get; } 
 

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.
@@ -124,7 +126,7 @@
         get => field;
         set
         {
             // TODO: In the next major release, Const should be made a JsonNode.
             // See https://github.com/microsoft/OpenAPI.NET/issues/2935 for more information.
             WasConstExplicitlySet = true;
             field = value;
@@ -267,6 +269,7 @@
     /// 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>
@@ -624,7 +627,7 @@
     protected override void SetAdditional31MetadataFromMapNode(JsonObject jsonObject)
 #pragma warning restore CS0809 // Obsolete member overrides non-obsolete member
     {
         //TODO remove this method in next major release
         // no-op: we're using ApplySchemaMetadata
     }
 

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

@@ -122,7 +122,7 @@
             get => field;
             set
             {
                 // TODO: In the next major release, Const should be made a JsonNode.
                 // See https://github.com/microsoft/OpenAPI.NET/issues/2935 for more information.
                 WasConstExplicitlySet = true;
                 field = value;
@@ -251,6 +251,7 @@
         public OpenApiDiscriminator? Discriminator { get; set; }
 
         /// <inheritdoc />
+        [Obsolete("Use Examples instead.")]
         public JsonNode? Example { get; set; }
 
         /// <inheritdoc />
@@ -963,7 +964,10 @@
             writer.WriteOptionalObject(OpenApiConstants.ExternalDocs, ExternalDocs, (w, s) => s.SerializeAsV2(w));
 
             // example
+#pragma warning disable CS0618
             writer.WriteOptionalObject(OpenApiConstants.Example, GetCompatibilityExample(), (w, e) => w.WriteAny(e));
+            writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, e) => w.WriteAny(e));
+#pragma warning restore CS0618
 
             // x-nullable extension
             SerializeNullable(writer, OpenApiSpecVersion.OpenApi2_0);
@@ -1032,7 +1036,9 @@
 
         private JsonNode? GetCompatibilityExample()
         {
+#pragma warning disable CS0618 // Type or member is obsolete
             return Example ?? Examples?.FirstOrDefault();
+#pragma warning restore CS0618 // Type or member is obsolete
         }
 
         private IEnumerable<JsonNode>? GetCompatibilityExamplesExtension()
@@ -1042,10 +1048,12 @@
                 return null;
             }
 
+#pragma warning disable CS0618 // Type or member is obsolete
             if (Example is not null)
             {
                 return Examples;
             }
+#pragma warning restore CS0618 // Type or member is obsolete
 
             return Examples.Count > 1 ? Examples.Skip(1) : null;
         }

src/Microsoft.OpenApi/Models/OpenApiXml.cs

@@ -30,7 +30,7 @@
         /// 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 @@
         /// 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 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 @@
         /// <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>

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

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

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

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

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

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

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

@@ -8,6 +8,8 @@
 using System.Text.Json;
 using System.Text.Json.Nodes;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Reader.V31;
 
 internal static partial class OpenApiV31Deserializer

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

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

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

@@ -8,6 +8,8 @@
 using System.Text.Json;
 using System.Text.Json.Nodes;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Reader.V32;
 
 internal static partial class OpenApiV32Deserializer

src/Microsoft.OpenApi/Validations/Rules/OpenApiNonDefaultRules.cs

@@ -7,6 +7,7 @@
 
 namespace Microsoft.OpenApi
 {
+#pragma warning disable CS0618
     /// <summary>
     /// Defines a non-default set of rules for validating examples in header, media type and parameter objects against the schema
     /// </summary>

test/Microsoft.OpenApi.Readers.Tests/V2Tests/OpenApiSchemaTests.cs

@@ -12,6 +12,8 @@
 using Microsoft.OpenApi.Tests;
 using Xunit;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Readers.Tests.V2Tests
 {
     [Collection("DefaultSettings")]

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDocumentTests.cs

@@ -10,6 +10,8 @@
 using System;
 using System.Net.Http;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Readers.Tests.V31Tests
 {
     public class OpenApiDocumentTests

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiSchemaTests.cs

@@ -14,6 +14,8 @@
 using Microsoft.OpenApi.Tests;
 using Xunit;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Readers.Tests.V31Tests
 {
     public class OpenApiSchemaTests

test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiDocumentTests.cs

@@ -10,6 +10,8 @@
 using System;
 using System.Net.Http;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Readers.Tests.V32Tests
 {
     public class OpenApiDocumentTests

test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiSchemaTests.cs

@@ -13,6 +13,8 @@
 using Xunit;
 using System;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Readers.Tests.V32Tests
 {
     public class OpenApiSchemaTests

test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiSchemaTests.cs

@@ -15,6 +15,8 @@
 using SharpYaml.Serialization;
 using Xunit;
 
+#pragma warning disable CS0618
+
 namespace Microsoft.OpenApi.Readers.Tests.V3Tests
 {
     [Collection("DefaultSettings")]

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

@@ -623,6 +623,7 @@ public static TheoryData<JsonNode> SchemaExamples()
 
         [Theory]
         [MemberData(nameof(SchemaExamples))]
+#pragma warning disable CS0618
         public void CloningSchemaExamplesWorks(JsonNode example)
         {
             // Arrange
@@ -639,6 +640,7 @@ public void CloningSchemaExamplesWorks(JsonNode example)
             .IgnoringCyclicReferences()
             .Excluding(x => x.Options));
         }
+#pragma warning restore CS0618
 
         [Fact]
         public void CloningSchemaExtensionsWorks()
@@ -1945,7 +1947,9 @@ public void DeserializeExamplesExtensionInV2AssignsExamplesProperty()
 
             Assert.Empty(readResult.Diagnostic.Errors);
             var schema = readResult.Document.Components.Schemas["TestSchema"];
+#pragma warning disable CS0618 // Type or member is obsolete
             Assert.Equal("primary example", schema.Example?.GetValue<string>());
+#pragma warning restore CS0618 // Type or member is obsolete
             Assert.NotNull(schema.Examples);
             Assert.Collection(
                 schema.Examples,
@@ -1981,7 +1985,9 @@ public void DeserializeExamplesExtensionInV3AssignsExamplesProperty()
 
             Assert.Empty(readResult.Diagnostic.Errors);
             var schema = readResult.Document.Components.Schemas["TestSchema"];
+#pragma warning disable CS0618 // Type or member is obsolete
             Assert.Equal("primary example", schema.Example?.GetValue<string>());
+#pragma warning restore CS0618 // Type or member is obsolete
             Assert.NotNull(schema.Examples);
             Assert.Collection(
                 schema.Examples,

test/Microsoft.OpenApi.Tests/Validations/OpenApiSchemaValidationTests.cs

@@ -36,6 +36,7 @@ public void ValidateDefaultShouldNotHaveDataTypeMismatchForSimpleSchema()
         }
 
         [Fact]
+#pragma warning disable CS0618
         public void ValidateExampleAndDefaultShouldNotHaveDataTypeMismatchForSimpleSchema()
         {
             // Arrange
@@ -58,6 +59,7 @@ public void ValidateExampleAndDefaultShouldNotHaveDataTypeMismatchForSimpleSchem
             // Assert
             Assert.True(result);
         }
+#pragma warning restore CS0618
 
         [Fact]
         public void ValidateEnumShouldNotHaveDataTypeMismatchForSimpleSchema()