Mark AddOpenApiForJsonApi with [Experimental]

Author: bkoelman

docs/usage/openapi.md

@@ -7,6 +7,9 @@ Exposing an [OpenAPI document](https://swagger.io/specification/) for your JSON:
 The [JsonApiDotNetCore.OpenApi.Swashbuckle](https://github.com/json-api-dotnet/JsonApiDotNetCore/pkgs/nuget/JsonApiDotNetCore.OpenApi.Swashbuckle) NuGet package
 provides OpenAPI support for JSON:API by integrating with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).
 
+> [!WARNING]
+> OpenAPI support for JSON:API is currently experimental. The API and the structure of the OpenAPI document may change in future versions.
+
 ## Getting started
 
 1.  Install the `JsonApiDotNetCore.OpenApi.Swashbuckle` NuGet package:

src/Examples/JsonApiDotNetCoreExample/Program.cs

@@ -79,7 +79,9 @@ static void ConfigureServices(WebApplicationBuilder builder)
 
     using (CodeTimingSessionManager.Current.Measure("AddOpenApiForJsonApi()"))
     {
+#pragma warning disable JADNC_OA_001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
         builder.Services.AddOpenApiForJsonApi(options => options.DocumentFilter<SetOpenApiServerAtBuildTimeFilter>());
+#pragma warning restore JADNC_OA_001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
     }
 }
 

src/JsonApiDotNetCore.OpenApi.Swashbuckle/ServiceCollectionExtensions.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics.CodeAnalysis;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiMetadata;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators.Bodies;
@@ -18,17 +19,18 @@ public static class ServiceCollectionExtensions
     /// <summary>
     /// Configures OpenAPI for JsonApiDotNetCore using Swashbuckle.
     /// </summary>
-    public static void AddOpenApiForJsonApi(this IServiceCollection services, Action<SwaggerGenOptions>? setupSwaggerGenAction = null)
+    [Experimental("JADNC_OA_001", UrlFormat = "https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/openapi/docs/usage/openapi.md")]
+    public static void AddOpenApiForJsonApi(this IServiceCollection services, Action<SwaggerGenOptions>? configureSwaggerGenOptions = null)
     {
         ArgumentNullException.ThrowIfNull(services);
 
         AddCustomApiExplorer(services);
         AddCustomSwaggerComponents(services);
         AddSwaggerGenerator(services);
 
-        if (setupSwaggerGenAction != null)
+        if (configureSwaggerGenOptions != null)
         {
-            services.Configure(setupSwaggerGenAction);
+            services.Configure(configureSwaggerGenOptions);
         }
     }
 

test/OpenApiTests/OpenApiStartup.cs

@@ -15,7 +15,9 @@ public override void ConfigureServices(IServiceCollection services)
     {
         base.ConfigureServices(services);
 
+#pragma warning disable JADNC_OA_001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
         services.AddOpenApiForJsonApi(SetupSwaggerGenAction);
+#pragma warning restore JADNC_OA_001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
     }
 
     protected override void SetJsonApiOptions(JsonApiOptions options)