Routing does not respect custom pluralized resource name (#805)

Author: maurei

benchmarks/DependencyFactory.cs

@@ -10,7 +10,7 @@ internal static class DependencyFactory
     {
         public static IResourceGraph CreateResourceGraph(IJsonApiOptions options)
         {
-            IResourceGraphBuilder builder = new ResourceGraphBuilder(options, NullLoggerFactory.Instance);
+            ResourceGraphBuilder builder = new ResourceGraphBuilder(options, NullLoggerFactory.Instance);
             builder.Add<BenchmarkResource>(BenchmarkResourcePublicNames.Type);
             return builder.Build();
         }

docs/usage/extensibility/middleware.md

@@ -1,14 +1,40 @@
 # Middleware
-Add the following to your Startup.ConfigureServices method. Replace AppDbContext with your DbContext.
 
-```c3
-services.AddJsonApi<AppDbContext>();
+It is possible to replace JsonApiDotNetCore middleware components by configuring the IoC container and by configuring `MvcOptions`. 
+
+## Configuring the IoC container 
+
+The following example replaces the internal exception filter with a custom implementation.
+```c#
+/// In Startup.ConfigureServices
+services.AddService<IAsyncJsonApiExceptionFilter, CustomAsyncExceptionFilter>()
 ```
 
-Add the middleware to the Startup.Configure method.
+## Configuring `MvcOptions`
+
+The following example replaces all internal filters with a custom filter.
+```c#
+/// In Startup.ConfigureServices
+services.AddSingleton<CustomAsyncQueryStringActionFilter>();
+
+var builder = services.AddMvcCore();
+services.AddJsonApi<AppDbContext>(mvcBuilder: builder);
 
-```c3
-app.UseRouting();
+// Ensure this call is placed after the AddJsonApi call.
+builder.AddMvcOptions(mvcOptions =>
+{
+    _postConfigureMvcOptions?.Invoke(mvcOptions);
+});
+
+/// In Startup.Configure
 app.UseJsonApi();
+
+// Ensure this call is placed before the UseEndpoints call.
+_postConfigureMvcOptions = mvcOptions => 
+{ 
+    mvcOptions.Filters.Clear();
+    mvcOptions.Filters.Insert(0, app.ApplicationServices.GetService<CustomAsyncQueryStringActionFilter>());
+};
+
 app.UseEndpoints(endpoints => endpoints.MapControllers());
 ```

docs/usage/options.md

@@ -90,8 +90,14 @@ options.SerializerSettings.Converters.Add(new StringEnumConverter());
 options.SerializerSettings.Formatting = Formatting.Indented;
 ```
 
+The default naming convention (as used in the routes and public resources names) is also determined here, and can be changed (default is camel-case):
+```c#
+options.SerializerSettings.ContractResolver = new DefaultContractResolver { NamingStrategy = new KebabCaseNamingStrategy() };
+```
+
 Because we copy resource properties into an intermediate object before serialization, Newtonsoft.Json annotations on properties are ignored.
 
+
 ## Enable ModelState Validation
 
 If you would like to use ASP.NET Core ModelState validation into your controllers when creating / updating resources, set `ValidateModelState = true`. By default, no model validation is performed.

docs/usage/resource-graph.md

@@ -14,10 +14,14 @@ There are three ways the resource graph can be created:
 2. Specifying an entire DbContext
 3. Manually specifying each resource
 
-### Auto-Discovery
+It is also possible to combine the three of them at once. Be aware that some configuration might overlap, 
+for example one could manually add a resource to the graph which is also auto-discovered. In such a scenario, the configuration
+is prioritized by the list above in descending order.
+
+### Auto-discovery
 
 Auto-discovery refers to the process of reflecting on an assembly and
-detecting all of the json:api resources and services.
+detecting all of the json:api resources, resource definitions, resource services and repositories.
 
 The following command will build the resource graph using all `IIdentifiable`
 implementations. It also injects resource definitions and service layer overrides which we will
@@ -34,9 +38,9 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
-### Entity Framework Core DbContext
+### Specifying an Entity Framework Core DbContext
 
-If you are using Entity Framework Core as your ORM, you can add an entire `DbContext` with one line.
+If you are using Entity Framework Core as your ORM, you can add all the models of a `DbContext`  to the resource graph.
 
 ```c#
 // Startup.cs
@@ -46,7 +50,7 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
-Be aware that the previous command does not inject resource definitions and service layer overrides. You can combine it with auto-discovery to register them.
+Be aware that this does not register resource definitions, resource services and repositories. You can combine it with auto-discovery to achieve this.
 
 ```c#
 // Startup.cs
@@ -60,31 +64,41 @@ public void ConfigureServices(IServiceCollection services)
 
 ### Manual Specification
 
-You can also manually construct the graph.
+You can manually construct the graph.
 
 ```c#
 // Startup.cs
 public void ConfigureServices(IServiceCollection services)
 {
     services.AddJsonApi(resources: builder =>
     {
-        builder.AddResource<Person>();
+        builder.Add<Person>();
     });
 }
 ```
 
-### Public Resource Type Name
+## Public Resource Name
+
+The public resource name is exposed through the `type` member in the json:api payload. This can be configured by the following approaches (in order of priority):
 
-The public resource type name is determined by the following criteria (in order of priority):
+1. The `publicName` parameter when manually adding a resource to the graph
+```c#
+services.AddJsonApi(resources: builder =>
+{
+    builder.Add<Person>(publicName: "people");
+});
+```
 
-1. The model is decorated with a `ResourceAttribute`
+2. The model is decorated with a `ResourceAttribute`
 ```c#
-[Resource("my-models")]
+[Resource("myResources")]
 public class MyModel : Identifiable { /* ... */ }
 ```
 
-2. The configured naming convention (by default this is camel-case).
+3. The configured naming convention (by default this is camel-case).
 ```c#
 // this will be registered as "myModels"
 public class MyModel : Identifiable { /* ... */ }
 ```
+
+The default naming convention can be changed in [options](./options.md#custom-serializer-settings).

docs/usage/resources/attributes.md

@@ -14,13 +14,8 @@ public class Person : Identifiable
 
 There are two ways the public attribute name is determined:
 
-1. By convention, specified in @JsonApiDotNetCore.Configuration.JsonApiOptions#JsonApiDotNetCore_Configuration_JsonApiOptions_SerializerSettings
-```c#
-options.SerializerSettings.ContractResolver = new DefaultContractResolver
-{
-    NamingStrategy = new KebabCaseNamingStrategy() // default: CamelCaseNamingStrategy
-};
-```
+1. Using the configured [naming convention](./options.md#custom-serializer-settings).
+
 
 2. Individually using the attribute's constructor
 ```c#

docs/usage/routing.md

@@ -1,15 +1,7 @@
 # Routing
 
-By default the library will configure routes for each controller.
-Based on the [recommendations](https://jsonapi.org/recommendations/) outlined in the json:api spec, routes are camel-cased.
-
-```http
-GET /api/compoundModels HTTP/1.1
-```
-
 ## Namespacing and Versioning URLs
-
-You can add a namespace to all URLs by specifying it in ConfigureServices
+You can add a namespace to all URLs by specifying it in ConfigureServices.
 
 ```c#
 public void ConfigureServices(IServiceCollection services)
@@ -20,40 +12,47 @@ public void ConfigureServices(IServiceCollection services)
 ```
 Which results in URLs like: https://yourdomain.com/api/v1/people
 
-## Disable Convention
+## Default Routing Convention
 
-You can disable the default casing convention and specify your own template by using the `DisableRoutingConvention` attribute.
+The library will configure routes for all controllers in your project. By default, routes are camel-cased. This is based on the [recommendations](https://jsonapi.org/recommendations/) outlined in the json:api spec.
 
 ```c#
-[Route("[controller]")]
-[DisableRoutingConvention]
-public class CamelCasedModelsController : JsonApiController<CamelCasedModel>
-{
-    public CamelCasedModelsController(
-        IJsonApiOptions options,
-        ILoggerFactory loggerFactory,
-        IResourceService<CamelCasedModel> resourceService)
-        : base(options, loggerFactory, resourceService)
-    { }
-}
+public class OrderLine : Identifiable {  }
+
+public class OrderLineController : JsonApiController<OrderLine> { /* .... */ }
+```
+
+```http
+GET /orderLines HTTP/1.1
 ```
 
-It is important to note that your routes must still end with the model name in the same format as the resource name. This is so that we can build accurate resource links in the json:api document. For example, if you define a resource as MyModels, the controller route must match.
+The public name of the resource ([which can be customized](./resource-graph.md#public-resource-name)) is used for the route, instead of the controller name.
 
+### Non-json:api controllers
+
+If a controller does not inherit from `JsonApiController<TResource>`, the [configured naming convention](./options.md#custom-serializer-settings) is applied to the name of the controller.
 ```c#
-public void ConfigureServices(IServiceCollection services)
-{
-    services.AddJsonApi(resources: builder =>
-        builder.AddResource<TodoItem>("my-models")); // kebab-cased
-}
+public class OrderLineController : ControllerBase { /* .... */ }
+```
+```http
+GET /orderLines HTTP/1.1
+```
 
-// controller definition
-[Route("api/my-models"), DisableRoutingConvention]
-public class MyModelsController : JsonApiController<TodoItem>
-{
-  //...
-}
+## Disabling the Default Routing Convention
+
+It is possible to bypass the default routing convention for a controller.
+```c#
+[Route("v1/custom/route/orderLines"), DisableRoutingConvention]
+public class OrderLineController : JsonApiController<OrderLine> { /* ... */ }
 ```
+It is required to match your custom url with the public name of the associated resource.
+
+## Advanced Usage: Custom Routing Convention
 
-See [this](~/usage/resource-graph.md#public-resource-type-name) for
-more information on how the resource name is determined.
+It is possible to replace the built-in routing convention with a [custom routing convention]](https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/application-model?view=aspnetcore-3.1#sample-custom-routing-convention) by registering an implementation of `IJsonApiRoutingConvention`.
+```c#
+public void ConfigureServices(IServiceCollection services)
+{
+	services.AddSingleton<IJsonApiRoutingConvention, CustomRoutingConvention>();
+}
+```

src/Examples/JsonApiDotNetCoreExample/Startups/Startup.cs

@@ -38,7 +38,7 @@ public override void ConfigureServices(IServiceCollection services)
             }, ServiceLifetime.Transient);
 
             services.AddJsonApi<AppDbContext>(ConfigureJsonApiOptions, discovery => discovery.AddCurrentAssembly());
-            
+
             // once all tests have been moved to WebApplicationFactory format we can get rid of this line below
             services.AddClientSerialization();
         }

src/JsonApiDotNetCore/Configuration/ApplicationBuilderExtensions.cs

@@ -1,6 +1,7 @@
 using System;
 using JsonApiDotNetCore.Middleware;
 using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
 
 namespace JsonApiDotNetCore.Configuration
 {
@@ -22,6 +23,23 @@ public static class ApplicationBuilderExtensions
         public static void UseJsonApi(this IApplicationBuilder builder)
         {
             if (builder == null) throw new ArgumentNullException(nameof(builder));
+            
+            using var scope = builder.ApplicationServices.GetRequiredService<IServiceScopeFactory>().CreateScope();
+            var inverseRelationshipResolver = scope.ServiceProvider.GetRequiredService<IInverseRelationships>();
+            inverseRelationshipResolver.Resolve();
+            
+            var jsonApiApplicationBuilder =  builder.ApplicationServices.GetRequiredService<IJsonApiApplicationBuilder>();
+            jsonApiApplicationBuilder.ConfigureMvcOptions = options =>
+            {
+                var inputFormatter = builder.ApplicationServices.GetRequiredService<IJsonApiInputFormatter>();
+                options.InputFormatters.Insert(0, inputFormatter);
+
+                var outputFormatter = builder.ApplicationServices.GetRequiredService<IJsonApiOutputFormatter>();
+                options.OutputFormatters.Insert(0, outputFormatter);
+
+                var routingConvention = builder.ApplicationServices.GetRequiredService<IJsonApiRoutingConvention>();
+                options.Conventions.Insert(0, routingConvention);
+            };
 
             builder.UseMiddleware<JsonApiMiddleware>();
         }

src/JsonApiDotNetCore/Configuration/IJsonApiApplicationBuilder.cs

@@ -0,0 +1,10 @@
+using System;
+using Microsoft.AspNetCore.Mvc;
+
+namespace JsonApiDotNetCore.Configuration
+{
+    internal interface IJsonApiApplicationBuilder
+    {
+        public Action<MvcOptions> ConfigureMvcOptions { set; }
+    }
+}

src/JsonApiDotNetCore/Configuration/IJsonApiOptions.cs

@@ -176,7 +176,7 @@ public interface IJsonApiOptions
         /// Specifies the settings that are used by the <see cref="JsonSerializer"/>.
         /// Note that at some places a few settings are ignored, to ensure json:api spec compliance.
         /// <example>
-        /// The next example changes the casing convention to kebab casing.
+        /// The next example changes the naming convention to kebab casing.
         /// <code><![CDATA[
         /// options.SerializerSettings.ContractResolver = new DefaultContractResolver
         /// {