Merge pull request #1450 from json-api-dotnet/openapi-filter-endpoints

bkoelman · web-flow · commit f7f8f8bae0ab · 2024-02-12T01:16:34.000+01:00
OpenAPI: Filter endpoints based on GenerateControllerEndpoints usage
diff --git a/src/JsonApiDotNetCore.OpenApi/JsonApiMetadata/EndpointResolver.cs b/src/JsonApiDotNetCore.OpenApi/JsonApiMetadata/EndpointResolver.cs
@@ -11,7 +11,6 @@ internal sealed class EndpointResolver
     {
         ArgumentGuard.NotNull(controllerAction);
 
-        // This is a temporary work-around to prevent the JsonApiDotNetCoreExample project from crashing upon startup.
         if (!IsJsonApiController(controllerAction) || IsOperationsController(controllerAction))
         {
             return null;
diff --git a/src/JsonApiDotNetCore.OpenApi/JsonApiMetadata/JsonApiEndpointMetadataProvider.cs b/src/JsonApiDotNetCore.OpenApi/JsonApiMetadata/JsonApiEndpointMetadataProvider.cs
@@ -34,7 +34,7 @@ public JsonApiEndpointMetadataContainer Get(MethodInfo controllerAction)
 
         if (endpoint == null)
         {
-            throw new NotSupportedException($"Unable to provide metadata for non-JsonApiDotNetCore endpoint '{controllerAction.ReflectedType!.FullName}'.");
+            throw new NotSupportedException($"Unable to provide metadata for non-JSON:API endpoint '{controllerAction.ReflectedType!.FullName}'.");
         }
 
         ResourceType? primaryResourceType = _controllerResourceMapping.GetResourceTypeForController(controllerAction.ReflectedType);
diff --git a/src/JsonApiDotNetCore.OpenApi/OpenApiEndpointConvention.cs b/src/JsonApiDotNetCore.OpenApi/OpenApiEndpointConvention.cs
@@ -1,4 +1,6 @@
+using System.Reflection;
 using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Controllers;
 using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.OpenApi.JsonApiMetadata;
 using JsonApiDotNetCore.Resources.Annotations;
@@ -29,48 +31,88 @@ public void Apply(ActionModel action)
 
         JsonApiEndpoint? endpoint = _endpointResolver.Get(action.ActionMethod);
 
-        if (endpoint == null || ShouldSuppressEndpoint(endpoint.Value, action.Controller.ControllerType))
+        if (endpoint == null)
         {
+            // Not a JSON:API controller, or a non-standard action method in a JSON:API controller, or an atomic:operations
+            // controller. None of these are yet implemented, so hide them to avoid downstream crashes.
             action.ApiExplorer.IsVisible = false;
+            return;
+        }
 
+        if (ShouldSuppressEndpoint(endpoint.Value, action.Controller.ControllerType))
+        {
+            action.ApiExplorer.IsVisible = false;
             return;
         }
 
         SetResponseMetadata(action, endpoint.Value);
-
         SetRequestMetadata(action, endpoint.Value);
     }
 
     private bool ShouldSuppressEndpoint(JsonApiEndpoint endpoint, Type controllerType)
     {
-        if (IsSecondaryOrRelationshipEndpoint(endpoint))
+        ResourceType? resourceType = _controllerResourceMapping.GetResourceTypeForController(controllerType);
+
+        if (resourceType == null)
+        {
+            throw new UnreachableCodeException();
+        }
+
+        if (!IsEndpointAvailable(endpoint, resourceType))
         {
-            IReadOnlyCollection<RelationshipAttribute> relationships = GetRelationshipsOfPrimaryResource(controllerType);
+            return true;
+        }
 
-            if (!relationships.Any())
+        if (IsSecondaryOrRelationshipEndpoint(endpoint))
+        {
+            if (!resourceType.Relationships.Any())
             {
                 return true;
             }
 
             if (endpoint is JsonApiEndpoint.DeleteRelationship or JsonApiEndpoint.PostRelationship)
             {
-                return !relationships.OfType<HasManyAttribute>().Any();
+                return !resourceType.Relationships.OfType<HasManyAttribute>().Any();
             }
         }
 
         return false;
     }
 
-    private IReadOnlyCollection<RelationshipAttribute> GetRelationshipsOfPrimaryResource(Type controllerType)
+    private static bool IsEndpointAvailable(JsonApiEndpoint endpoint, ResourceType resourceType)
     {
-        ResourceType? primaryResourceType = _controllerResourceMapping.GetResourceTypeForController(controllerType);
+        JsonApiEndpoints availableEndpoints = GetGeneratedControllerEndpoints(resourceType);
 
-        if (primaryResourceType == null)
+        if (availableEndpoints == JsonApiEndpoints.None)
         {
-            throw new UnreachableCodeException();
+            // Auto-generated controllers are disabled, so we can't know what to hide.
+            // It is assumed that a handwritten JSON:API controller only provides action methods for what it supports.
+            // To accomplish that, derive from BaseJsonApiController instead of JsonApiController.
+            return true;
         }
 
-        return primaryResourceType.Relationships;
+        // For an overridden JSON:API action method in a partial class to show up, it's flag must be turned on in [Resource].
+        // Otherwise, it is considered to be an action method that throws because the endpoint is unavailable.
+        return endpoint switch
+        {
+            JsonApiEndpoint.GetCollection => availableEndpoints.HasFlag(JsonApiEndpoints.GetCollection),
+            JsonApiEndpoint.GetSingle => availableEndpoints.HasFlag(JsonApiEndpoints.GetSingle),
+            JsonApiEndpoint.GetSecondary => availableEndpoints.HasFlag(JsonApiEndpoints.GetSecondary),
+            JsonApiEndpoint.GetRelationship => availableEndpoints.HasFlag(JsonApiEndpoints.GetRelationship),
+            JsonApiEndpoint.Post => availableEndpoints.HasFlag(JsonApiEndpoints.Post),
+            JsonApiEndpoint.PostRelationship => availableEndpoints.HasFlag(JsonApiEndpoints.PostRelationship),
+            JsonApiEndpoint.Patch => availableEndpoints.HasFlag(JsonApiEndpoints.Patch),
+            JsonApiEndpoint.PatchRelationship => availableEndpoints.HasFlag(JsonApiEndpoints.PatchRelationship),
+            JsonApiEndpoint.Delete => availableEndpoints.HasFlag(JsonApiEndpoints.Delete),
+            JsonApiEndpoint.DeleteRelationship => availableEndpoints.HasFlag(JsonApiEndpoints.DeleteRelationship),
+            _ => throw new UnreachableCodeException()
+        };
+    }
+
+    private static JsonApiEndpoints GetGeneratedControllerEndpoints(ResourceType resourceType)
+    {
+        var resourceAttribute = resourceType.ClrType.GetCustomAttribute<ResourceAttribute>();
+        return resourceAttribute?.GenerateControllerEndpoints ?? JsonApiEndpoints.None;
     }
 
     private static bool IsSecondaryOrRelationshipEndpoint(JsonApiEndpoint endpoint)
diff --git a/src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs b/src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs
@@ -1,8 +1,6 @@
-using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.OpenApi.SwaggerComponents;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
-using Microsoft.AspNetCore.Mvc.Infrastructure;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Microsoft.Extensions.Options;
@@ -36,18 +34,14 @@ public static void AddOpenApi(this IServiceCollection services, IMvcCoreBuilder
     private static void AddCustomApiExplorer(IServiceCollection services, IMvcCoreBuilder mvcBuilder)
     {
         services.TryAddSingleton<ResourceFieldValidationMetadataProvider>();
+        services.AddSingleton<JsonApiActionDescriptorCollectionProvider>();
 
-        services.TryAddSingleton<IApiDescriptionGroupCollectionProvider>(provider =>
+        services.TryAddSingleton<IApiDescriptionGroupCollectionProvider>(serviceProvider =>
         {
-            var controllerResourceMapping = provider.GetRequiredService<IControllerResourceMapping>();
-            var actionDescriptorCollectionProvider = provider.GetRequiredService<IActionDescriptorCollectionProvider>();
-            var apiDescriptionProviders = provider.GetRequiredService<IEnumerable<IApiDescriptionProvider>>();
-            var resourceFieldValidationMetadataProvider = provider.GetRequiredService<ResourceFieldValidationMetadataProvider>();
+            var actionDescriptorCollectionProvider = serviceProvider.GetRequiredService<JsonApiActionDescriptorCollectionProvider>();
+            var apiDescriptionProviders = serviceProvider.GetRequiredService<IEnumerable<IApiDescriptionProvider>>();
 
-            JsonApiActionDescriptorCollectionProvider jsonApiActionDescriptorCollectionProvider =
-                new(controllerResourceMapping, actionDescriptorCollectionProvider, resourceFieldValidationMetadataProvider);
-
-            return new ApiDescriptionGroupCollectionProvider(jsonApiActionDescriptorCollectionProvider, apiDescriptionProviders);
+            return new ApiDescriptionGroupCollectionProvider(actionDescriptorCollectionProvider, apiDescriptionProviders);
         });
 
         mvcBuilder.AddApiExplorer();
diff --git a/test/OpenApiTests/RestrictedControllers/Channel.cs b/test/OpenApiTests/RestrictedControllers/Channel.cs
@@ -0,0 +1,18 @@
+using JetBrains.Annotations;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
+
+namespace OpenApiTests.RestrictedControllers;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+public abstract class Channel : Identifiable<long>
+{
+    [Attr]
+    public string? Name { get; set; }
+
+    [HasOne]
+    public DataStream VideoStream { get; set; } = null!;
+
+    [HasMany]
+    public ISet<DataStream> AudioStreams { get; set; } = new HashSet<DataStream>();
+}
diff --git a/test/OpenApiTests/RestrictedControllers/DataStream.cs b/test/OpenApiTests/RestrictedControllers/DataStream.cs
@@ -0,0 +1,16 @@
+using System.ComponentModel.DataAnnotations;
+using JetBrains.Annotations;
+using JsonApiDotNetCore.Controllers;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
+
+namespace OpenApiTests.RestrictedControllers;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+[Resource(ControllerNamespace = "OpenApiTests.RestrictedControllers", GenerateControllerEndpoints = JsonApiEndpoints.None)]
+public sealed class DataStream : Identifiable<long>
+{
+    [Attr]
+    [Required]
+    public ulong? BytesTransmitted { get; set; }
+}
diff --git a/test/OpenApiTests/RestrictedControllers/DataStreamController.cs b/test/OpenApiTests/RestrictedControllers/DataStreamController.cs
@@ -0,0 +1,26 @@
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Controllers;
+using JsonApiDotNetCore.Services;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Logging;
+
+namespace OpenApiTests.RestrictedControllers;
+
+public sealed class DataStreamController(
+    IJsonApiOptions options, IResourceGraph resourceGraph, ILoggerFactory loggerFactory, IResourceService<DataStream, long> resourceService)
+    : BaseJsonApiController<DataStream, long>(options, resourceGraph, loggerFactory, resourceService)
+{
+    [HttpGet]
+    [HttpHead]
+    public override Task<IActionResult> GetAsync(CancellationToken cancellationToken)
+    {
+        return base.GetAsync(cancellationToken);
+    }
+
+    [HttpGet("{id}")]
+    [HttpHead("{id}")]
+    public override Task<IActionResult> GetAsync(long id, CancellationToken cancellationToken)
+    {
+        return base.GetAsync(id, cancellationToken);
+    }
+}
diff --git a/test/OpenApiTests/RestrictedControllers/ReadOnlyChannel.cs b/test/OpenApiTests/RestrictedControllers/ReadOnlyChannel.cs
@@ -0,0 +1,12 @@
+﻿using JetBrains.Annotations;
+using JsonApiDotNetCore.Controllers;
+using JsonApiDotNetCore.Resources.Annotations;
+
+namespace OpenApiTests.RestrictedControllers;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+[Resource(ControllerNamespace = "OpenApiTests.RestrictedControllers", GenerateControllerEndpoints = ControllerEndpoints)]
+public sealed class ReadOnlyChannel : Channel
+{
+    internal const JsonApiEndpoints ControllerEndpoints = JsonApiEndpoints.Query;
+}
diff --git a/test/OpenApiTests/RestrictedControllers/ReadOnlyResourceChannel.cs b/test/OpenApiTests/RestrictedControllers/ReadOnlyResourceChannel.cs
@@ -0,0 +1,12 @@
+using JetBrains.Annotations;
+using JsonApiDotNetCore.Controllers;
+using JsonApiDotNetCore.Resources.Annotations;
+
+namespace OpenApiTests.RestrictedControllers;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+[Resource(ControllerNamespace = "OpenApiTests.RestrictedControllers", GenerateControllerEndpoints = ControllerEndpoints)]
+public sealed class ReadOnlyResourceChannel : Channel
+{
+    internal const JsonApiEndpoints ControllerEndpoints = JsonApiEndpoints.GetCollection | JsonApiEndpoints.GetSingle | JsonApiEndpoints.GetSecondary;
+}
diff --git a/test/OpenApiTests/RestrictedControllers/RelationshipChannel.cs b/test/OpenApiTests/RestrictedControllers/RelationshipChannel.cs
@@ -0,0 +1,13 @@
+﻿using JetBrains.Annotations;
+using JsonApiDotNetCore.Controllers;
+using JsonApiDotNetCore.Resources.Annotations;
+
+namespace OpenApiTests.RestrictedControllers;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+[Resource(ControllerNamespace = "OpenApiTests.RestrictedControllers", GenerateControllerEndpoints = ControllerEndpoints)]
+public sealed class RelationshipChannel : Channel
+{
+    internal const JsonApiEndpoints ControllerEndpoints = JsonApiEndpoints.GetRelationship | JsonApiEndpoints.PostRelationship |
+        JsonApiEndpoints.PatchRelationship | JsonApiEndpoints.DeleteRelationship;
+}
diff --git a/test/OpenApiTests/RestrictedControllers/RestrictionDbContext.cs b/test/OpenApiTests/RestrictedControllers/RestrictionDbContext.cs
@@ -0,0 +1,15 @@
+using JetBrains.Annotations;
+using Microsoft.EntityFrameworkCore;
+using TestBuildingBlocks;
+
+namespace OpenApiTests.RestrictedControllers;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+public sealed class RestrictionDbContext(DbContextOptions<RestrictionDbContext> options) : TestableDbContext(options)
+{
+    public DbSet<DataStream> DataStreams => Set<DataStream>();
+    public DbSet<ReadOnlyChannel> ReadOnlyChannels => Set<ReadOnlyChannel>();
+    public DbSet<WriteOnlyChannel> WriteOnlyChannels => Set<WriteOnlyChannel>();
+    public DbSet<RelationshipChannel> RelationshipChannels => Set<RelationshipChannel>();
+    public DbSet<ReadOnlyResourceChannel> ReadOnlyResourceChannels => Set<ReadOnlyResourceChannel>();
+}
diff --git a/test/OpenApiTests/RestrictedControllers/RestrictionFakers.cs b/test/OpenApiTests/RestrictedControllers/RestrictionFakers.cs
@@ -0,0 +1,38 @@
+using Bogus;
+using JetBrains.Annotations;
+using TestBuildingBlocks;
+
+// @formatter:wrap_chained_method_calls chop_if_long
+// @formatter:wrap_before_first_method_call true
+
+namespace OpenApiTests.RestrictedControllers;
+
+[UsedImplicitly(ImplicitUseTargetFlags.Members)]
+public sealed class RestrictionFakers : FakerContainer
+{
+    private readonly Lazy<Faker<DataStream>> _lazyDataStreamFaker = new(() => new Faker<DataStream>()
+        .UseSeed(GetFakerSeed())
+        .RuleFor(stream => stream.BytesTransmitted, faker => faker.Random.ULong()));
+
+    private readonly Lazy<Faker<ReadOnlyChannel>> _lazyReadOnlyChannelFaker = new(() => new Faker<ReadOnlyChannel>()
+        .UseSeed(GetFakerSeed())
+        .RuleFor(channel => channel.Name, faker => faker.Lorem.Word()));
+
+    private readonly Lazy<Faker<WriteOnlyChannel>> _lazyWriteOnlyChannelFaker = new(() => new Faker<WriteOnlyChannel>()
+        .UseSeed(GetFakerSeed())
+        .RuleFor(channel => channel.Name, faker => faker.Lorem.Word()));
+
+    private readonly Lazy<Faker<RelationshipChannel>> _lazyRelationshipChannelFaker = new(() => new Faker<RelationshipChannel>()
+        .UseSeed(GetFakerSeed())
+        .RuleFor(channel => channel.Name, faker => faker.Lorem.Word()));
+
+    private readonly Lazy<Faker<ReadOnlyResourceChannel>> _lazyReadOnlyResourceChannelFaker = new(() => new Faker<ReadOnlyResourceChannel>()
+        .UseSeed(GetFakerSeed())
+        .RuleFor(channel => channel.Name, faker => faker.Lorem.Word()));
+
+    public Faker<DataStream> DataStream => _lazyDataStreamFaker.Value;
+    public Faker<ReadOnlyChannel> ReadOnlyChannel => _lazyReadOnlyChannelFaker.Value;
+    public Faker<WriteOnlyChannel> WriteOnlyChannel => _lazyWriteOnlyChannelFaker.Value;
+    public Faker<RelationshipChannel> RelationshipChannel => _lazyRelationshipChannelFaker.Value;
+    public Faker<ReadOnlyResourceChannel> ReadOnlyResourceChannel => _lazyReadOnlyResourceChannelFaker.Value;
+}
diff --git a/test/OpenApiTests/RestrictedControllers/RestrictionTests.cs b/test/OpenApiTests/RestrictedControllers/RestrictionTests.cs
diff --git a/test/OpenApiTests/RestrictedControllers/WriteOnlyChannel.cs b/test/OpenApiTests/RestrictedControllers/WriteOnlyChannel.cs

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,6 @@ internal sealed class EndpointResolver`
`11`	`11`	`{`
`12`	`12`	`ArgumentGuard.NotNull(controllerAction);`
`13`	`13`
`14`		`- // This is a temporary work-around to prevent the JsonApiDotNetCoreExample project from crashing upon startup.`
`15`	`14`	`if (!IsJsonApiController(controllerAction) \|\| IsOperationsController(controllerAction))`
`16`	`15`	`{`
`17`	`16`	`return null;`
Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,7 @@ public JsonApiEndpointMetadataContainer Get(MethodInfo controllerAction)`
`34`	`34`
`35`	`35`	`if (endpoint == null)`
`36`	`36`	`{`
`37`		`- throw new NotSupportedException($"Unable to provide metadata for non-JsonApiDotNetCore endpoint '{controllerAction.ReflectedType!.FullName}'.");`
	`37`	`+ throw new NotSupportedException($"Unable to provide metadata for non-JSON:API endpoint '{controllerAction.ReflectedType!.FullName}'.");`
`38`	`38`	`}`
`39`	`39`
`40`	`40`	`ResourceType? primaryResourceType = _controllerResourceMapping.GetResourceTypeForController(controllerAction.ReflectedType);`