chore: marks new APIs as experimental

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

Author: baywet

src/Microsoft.OpenApi/Attributes/ExperimentalAttribute.cs

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+// Polyfill for ExperimentalAttribute which is only available in .NET 8+.
+// Since the compiler queries for this attribute by name, having it source-included
+// is sufficient for the compiler to recognize it.
+namespace System.Diagnostics.CodeAnalysis
+{
+#if !NET8_0_OR_GREATER
+    /// <summary>
+    /// Indicates that an API is experimental and it may change in the future.
+    /// </summary>
+    /// <remarks>
+    /// This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental
+    /// feature is used. Authors can use this attribute to ship preview features in their assemblies.
+    /// </remarks>
+    [AttributeUsage(
+        AttributeTargets.Assembly | AttributeTargets.Module | AttributeTargets.Class | AttributeTargets.Struct |
+        AttributeTargets.Enum | AttributeTargets.Constructor | AttributeTargets.Method | AttributeTargets.Property |
+        AttributeTargets.Field | AttributeTargets.Event | AttributeTargets.Interface | AttributeTargets.Delegate,
+        Inherited = false)]
+    internal sealed class ExperimentalAttribute : Attribute
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ExperimentalAttribute"/> class,
+        /// specifying the ID that the compiler will use when reporting a use of the API.
+        /// </summary>
+        /// <param name="diagnosticId">The ID that the compiler will use when reporting a use of the API.</param>
+        public ExperimentalAttribute(string diagnosticId)
+        {
+            DiagnosticId = diagnosticId;
+        }
+
+        /// <summary>
+        /// Gets the ID that the compiler will use when reporting a use of the API.
+        /// </summary>
+        public string DiagnosticId { get; }
+
+        /// <summary>
+        /// Gets or sets the URL for corresponding documentation.
+        /// The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID.
+        /// </summary>
+        public string? UrlFormat { get; set; }
+    }
+#endif
+}

src/Microsoft.OpenApi/Services/OpenApiPathHelper.cs

@@ -1,14 +1,17 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+#pragma warning disable OAI020 // Internal implementation uses experimental APIs
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Microsoft.OpenApi;
 
 /// <summary>
 /// Provides helper methods for converting OpenAPI JSON Pointer paths between specification versions.
 /// </summary>
+[Experimental("OAI020", UrlFormat = "https://aka.ms/openapi/net/experimental/{0}")]
 public static class OpenApiPathHelper
 {
     private static readonly Dictionary<OpenApiSpecVersion, IOpenApiPathRepresentationPolicy[]> _policies = new()

src/Microsoft.OpenApi/Validations/OpenApiValidatorError.cs

@@ -1,6 +1,9 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+#pragma warning disable OAI020 // Internal implementation uses experimental APIs
+using System.Diagnostics.CodeAnalysis;
+
 namespace Microsoft.OpenApi
 {
     /// <summary>
@@ -29,6 +32,7 @@ public OpenApiValidatorError(string ruleName, string pointer, string message) :
         /// The equivalent pointer in the target version, the original pointer if no transformation is needed,
         /// or <c>null</c> if the pointer has no equivalent in the target version.
         /// </returns>
+        [Experimental("OAI020", UrlFormat = "https://aka.ms/openapi/net/experimental/{0}")]
         public string? GetVersionedPointer(OpenApiSpecVersion targetVersion)
         {
             if (Pointer is null)

test/Microsoft.OpenApi.Tests/Services/OpenApiPathHelperTests.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT license.
 
 #nullable enable
+#pragma warning disable OAI020 // Type is for evaluation purposes only
 using Xunit;
 
 namespace Microsoft.OpenApi.Tests.Services;