Merge pull request #1663 from json-api-dotnet/openapi-mark-experimental

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.Client.NSwag/JsonApiClient.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Linq.Expressions;
 using System.Reflection;
 using Newtonsoft.Json;
@@ -175,7 +176,7 @@ public override bool CanConvert(Type objectType)
 
         public override object ReadJson(JsonReader reader, Type objectType, object? existingValue, JsonSerializer serializer)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         public override void WriteJson(JsonWriter writer, object? value, JsonSerializer serializer)
@@ -236,7 +237,7 @@ public override bool CanConvert(Type objectType)
 
         public override object ReadJson(JsonReader reader, Type objectType, object? existingValue, JsonSerializer serializer)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         public override void WriteJson(JsonWriter writer, object? value, JsonSerializer serializer)

src/JsonApiDotNetCore.OpenApi.Client.NSwag/UnreachableCodeException.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Reflection;
 using JsonApiDotNetCore.Errors;
 using JsonApiDotNetCore.Middleware;
@@ -125,7 +126,7 @@ private static void UpdateProducesResponseTypeAttribute(ActionDescriptor endpoin
             }
         }
 
-        throw new UnreachableCodeException();
+        throw new UnreachableException();
     }
 
     private static bool ProducesJsonApiResponseDocument(ActionDescriptor endpoint)

src/JsonApiDotNetCore.OpenApi.Swashbuckle/JsonApiActionDescriptorCollectionProvider.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Reflection;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Controllers;
@@ -45,7 +46,7 @@ public JsonApiEndpointMetadataContainer Get(MethodInfo controllerAction)
 
         if (primaryResourceType == null)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         IJsonApiRequestMetadata? requestMetadata = GetRequestMetadata(endpoint, primaryResourceType);

src/JsonApiDotNetCore.OpenApi.Swashbuckle/JsonApiMetadata/JsonApiEndpointMetadataProvider.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using JsonApiDotNetCore.Middleware;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.AspNetCore.Mvc.Formatters;
@@ -18,7 +19,7 @@ public bool CanRead(InputFormatterContext context)
     /// <inheritdoc />
     public Task<InputFormatterResult> ReadAsync(InputFormatterContext context)
     {
-        throw new UnreachableCodeException();
+        throw new UnreachableException();
     }
 
     /// <inheritdoc />

src/JsonApiDotNetCore.OpenApi.Swashbuckle/JsonApiRequestFormatMetadataProvider.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Net;
 using System.Reflection;
 using JsonApiDotNetCore.Configuration;
@@ -108,7 +109,7 @@ private static bool IsEndpointAvailable(JsonApiEndpoints endpoint, ResourceType
             JsonApiEndpoints.PatchRelationship => availableEndpoints.HasFlag(JsonApiEndpoints.PatchRelationship),
             JsonApiEndpoints.Delete => availableEndpoints.HasFlag(JsonApiEndpoints.Delete),
             JsonApiEndpoints.DeleteRelationship => availableEndpoints.HasFlag(JsonApiEndpoints.DeleteRelationship),
-            _ => throw new UnreachableCodeException()
+            _ => throw new UnreachableException()
         };
     }
 
@@ -178,7 +179,7 @@ private static HttpStatusCode[] GetSuccessStatusCodesForEndpoint(JsonApiEndpoint
             [
                 HttpStatusCode.NoContent
             ],
-            _ => throw new UnreachableCodeException()
+            _ => throw new UnreachableException()
         };
     }
 
@@ -236,7 +237,7 @@ private HttpStatusCode[] GetErrorStatusCodesForEndpoint(JsonApiEndpointWrapper e
                 HttpStatusCode.NotFound,
                 HttpStatusCode.Conflict
             ],
-            _ => throw new UnreachableCodeException()
+            _ => throw new UnreachableException()
         };
     }
 

src/JsonApiDotNetCore.OpenApi.Swashbuckle/OpenApiEndpointConvention.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Reflection;
 using System.Text.Json;
 using Humanizer;
@@ -66,7 +67,7 @@ private static string GetTemplate(ApiDescription endpoint)
 
         if (!SchemaOpenTypeToOpenApiOperationIdTemplateMap.TryGetValue(bodyType, out string? template))
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         return template;
@@ -78,7 +79,7 @@ private static Type GetBodyType(ApiDescription endpoint)
 
         if (producesResponseTypeAttribute == null)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         ControllerParameterDescriptor? requestBodyDescriptor = endpoint.ActionDescriptor.GetBodyParameterDescriptor();
@@ -96,7 +97,7 @@ private string ApplyTemplate(string openApiOperationIdTemplate, ResourceType? re
     {
         if (endpoint.RelativePath == null || endpoint.HttpMethod == null)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         string method = endpoint.HttpMethod.ToLowerInvariant();

src/JsonApiDotNetCore.OpenApi.Swashbuckle/OpenApiOperationIdSelector.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using Microsoft.OpenApi.Models;
 
 namespace JsonApiDotNetCore.OpenApi.Swashbuckle;
@@ -21,7 +22,7 @@ public static void ReorderProperties(this OpenApiSchema fullSchema, IEnumerable<
 
         if (fullSchema.Properties.Count != propertiesInOrder.Count)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         fullSchema.Properties = propertiesInOrder;