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;

src/JsonApiDotNetCore.OpenApi.Swashbuckle/OpenApiSchemaExtensions.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using JsonApiDotNetCore.AtomicOperations;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Middleware;
@@ -121,7 +122,7 @@ private void GenerateSchemaForResourceOperation(Type operationOpenType, Resource
             AtomicOperationCode.Add => WriteOperationKind.CreateResource,
             AtomicOperationCode.Update => WriteOperationKind.UpdateResource,
             AtomicOperationCode.Remove => WriteOperationKind.DeleteResource,
-            _ => throw new UnreachableCodeException()
+            _ => throw new UnreachableException()
         };
 
         if (!_atomicOperationFilter.IsEnabled(resourceType, writeOperation))
@@ -158,7 +159,7 @@ private void GenerateSchemaForRelationshipOperation(Type operationOpenType, Rela
             AtomicOperationCode.Add => WriteOperationKind.AddToRelationship,
             AtomicOperationCode.Update => WriteOperationKind.SetRelationship,
             AtomicOperationCode.Remove => WriteOperationKind.RemoveFromRelationship,
-            _ => throw new UnreachableCodeException()
+            _ => throw new UnreachableException()
         };
 
         if (!_atomicOperationFilter.IsEnabled(relationship.LeftType, writeOperation))
@@ -211,7 +212,7 @@ private static bool IsToOneRelationshipEnabled(HasOneAttribute relationship, Wri
         return writeOperation switch
         {
             WriteOperationKind.SetRelationship => relationship.Capabilities.HasFlag(HasOneCapabilities.AllowSet),
-            _ => throw new UnreachableCodeException()
+            _ => throw new UnreachableException()
         };
     }
 
@@ -222,7 +223,7 @@ private static bool IsToManyRelationshipEnabled(HasManyAttribute relationship, W
             WriteOperationKind.SetRelationship => relationship.Capabilities.HasFlag(HasManyCapabilities.AllowSet),
             WriteOperationKind.AddToRelationship => relationship.Capabilities.HasFlag(HasManyCapabilities.AllowAdd),
             WriteOperationKind.RemoveFromRelationship => relationship.Capabilities.HasFlag(HasManyCapabilities.AllowRemove),
-            _ => throw new UnreachableCodeException()
+            _ => throw new UnreachableException()
         };
     }
 

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Bodies/AtomicOperationsBodySchemaGenerator.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiObjects.AtomicOperations;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
@@ -74,7 +75,7 @@ public void MapDiscriminator(OpenApiSchema referenceSchemaForOperation, string d
 
         if (!schemaRepository.TryLookupByType(AtomicOperationAbstractType, out OpenApiSchema? referenceSchemaForAbstractOperation))
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         OpenApiSchema fullSchemaForAbstractOperation = schemaRepository.Schemas[referenceSchemaForAbstractOperation.Reference.Id];

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Components/AbstractAtomicOperationSchemaGenerator.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiObjects.ResourceObjects;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.SwaggerComponents;
@@ -97,7 +98,7 @@ public void MapDiscriminator(Type resourceDataConstructedType, OpenApiSchema ref
         {
             if (!schemaRepository.TryLookupByType(ResourceDataAbstractType, out OpenApiSchema? referenceSchemaForAbstractResourceData))
             {
-                throw new UnreachableCodeException();
+                throw new UnreachableException();
             }
 
             OpenApiSchema fullSchemaForAbstractResourceData = schemaRepository.Schemas[referenceSchemaForAbstractResourceData.Reference.Id];

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Components/AbstractResourceDataSchemaGenerator.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Reflection;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiObjects.ResourceObjects;
@@ -75,7 +76,7 @@ private static Type GetElementTypeOfDataProperty(Type dataContainerConstructedTy
 
         if (dataProperty == null)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         Type innerPropertyType = dataProperty.PropertyType.ConstructedToOpenType().IsAssignableTo(typeof(ICollection<>))
@@ -89,7 +90,7 @@ private static Type GetElementTypeOfDataProperty(Type dataContainerConstructedTy
 
         if (!innerPropertyType.IsGenericType)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         return innerPropertyType;

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Components/DataContainerSchemaGenerator.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiObjects.ResourceObjects;
 using JsonApiDotNetCore.Resources.Annotations;
@@ -54,7 +55,7 @@ public OpenApiSchema GenerateSchema(RelationshipAttribute relationship, SchemaRe
 
         if (schemaRepository.TryLookupByType(relationshipIdentifierConstructedType, out _))
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         OpenApiSchema referenceSchemaForIdentifier = _defaultSchemaGenerator.GenerateSchema(relationshipIdentifierConstructedType, schemaRepository);

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/Components/RelationshipIdentifierSchemaGenerator.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Reflection;
 using JsonApiDotNetCore.Controllers;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.SchemaGenerators.Bodies;
@@ -61,6 +62,6 @@ private BodySchemaGenerator GetBodySchemaGenerator(Type modelType)
             }
         }
 
-        throw new UnreachableCodeException();
+        throw new UnreachableException();
     }
 }

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SchemaGenerators/JsonApiSchemaGenerator.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);
         }
     }
 

src/JsonApiDotNetCore.OpenApi.Swashbuckle/ServiceCollectionExtensions.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Net;
 using System.Reflection;
 using Humanizer;
@@ -437,7 +438,7 @@ private static RelationshipAttribute GetRelationshipFromRoute(ApiDescription api
     {
         if (apiDescription.RelativePath == null)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
 
         string relationshipName = apiDescription.RelativePath.Split('/').Last();

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SwaggerComponents/DocumentationOpenApiOperationFilter.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Reflection;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiMetadata;
 using JsonApiDotNetCore.OpenApi.Swashbuckle.JsonApiObjects.ResourceObjects;
@@ -109,7 +110,7 @@ private static AttrCapabilities GetRequiredCapabilityForAttributes(Type resource
     {
         return resourceDataOpenType == typeof(ResourceDataInResponse<>) ? AttrCapabilities.AllowView :
             resourceDataOpenType == typeof(DataInCreateResourceRequest<>) ? AttrCapabilities.AllowCreate :
-            resourceDataOpenType == typeof(DataInUpdateResourceRequest<>) ? AttrCapabilities.AllowChange : throw new UnreachableCodeException();
+            resourceDataOpenType == typeof(DataInUpdateResourceRequest<>) ? AttrCapabilities.AllowChange : throw new UnreachableException();
     }
 
     private void EnsureAttributeSchemaIsExposed(OpenApiSchema referenceSchemaForAttribute, AttrAttribute attribute, SchemaRepository schemaRepository)
@@ -219,7 +220,7 @@ private static void AssertHasNoProperties(OpenApiSchema fullSchema)
     {
         if (fullSchema.Properties.Count > 0)
         {
-            throw new UnreachableCodeException();
+            throw new UnreachableException();
         }
     }
 }

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SwaggerComponents/ResourceFieldSchemaBuilder.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using JetBrains.Annotations;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Interfaces;
@@ -52,7 +53,7 @@ private static void OrderEnumMembers(OpenApiSchema schema)
 
             if (ordered.Count != schema.Enum.Count)
             {
-                throw new UnreachableCodeException();
+                throw new UnreachableException();
             }
 
             schema.Enum = ordered;

src/JsonApiDotNetCore.OpenApi.Swashbuckle/SwaggerComponents/StringEnumOrderingFilter.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)