Routing does not respect custom pluralized resource name

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,84 @@
 # Middleware
-Add the following to your Startup.ConfigureServices method. Replace AppDbContext with your DbContext.
 
-```c3
+The following is the default configuration of JsonApiDotNetCore:
+1. Call one of the `AddJsonApi( ... )` overloads in the ` Startup.ConfigureServices` method. In this example uses a `DbContext` to build the resource graph
+
+```c#
 services.AddJsonApi<AppDbContext>();
 ```
 
-Add the middleware to the Startup.Configure method.
+2. In the Startup.Configure method, configure your application to use routing, to add the JsonApiMiddleware and to configure endpoint routing.
 
-```c3
+```c#
 app.UseRouting();
 app.UseJsonApi();
 app.UseEndpoints(endpoints => endpoints.MapControllers());
 ```
+
+The following middleware components, in respective order, are registered:
+
+Filters:
+- `IJsonApiExceptionFilter`
+- `IJsonApiTypeMatchFilter`
+- `IQueryStringActionFilter`
+- `IConvertEmptyActionResultFilter`
+
+Formatters:
+- `IJsonApiInputFormatter`
+- `IJsonApiOutputFormatter`
+
+Routing convention:
+- `IJsonApiRoutingConvention`
+
+Middleware:
+- `JsonApiMiddleware`
+
+All of these components (except for `JsonApiMiddleware`) can be customized by registering your own implementation of these services. For example:
+
+```c#
+services.AddSingleton<IJsonApiExceptionFilter, MyCustomExceptionFilter>();
+```
+
+It is also possible to directly access the .NET Core `MvcOptions` object and have full controll over which components are registered. 
+
+## Configuring MvcOptions
+
+JsonApiDotNetCore internally configures `MvcOptions` when calling `AddJsonApi( ... )`. However, it is still possible to register a custom configuration callback. To achieve this it is recommended to register this callback *after* the `AddJsonApi( ... )` call. It is also possible to do it earlier, but your configuration might be overridden by the JsonApiDotNetCore configuration. 
+
+The following example replaces all internally registered filters by retrieving a custom filter from the DI container.
+```c#
+public class Startup
+{
+    private Action<MvcOptions> _postConfigureMvcOptions;
+
+    public void ConfigureServices(IServiceCollection services)
+    {
+        ...
+
+        var builder = services.AddMvcCore();
+        services.AddJsonApi<AppDbContext>( ... , mvcBuilder: builder);
+        mvcCoreBuilder.AddMvcOptions(x =>
+        {
+            // execute the mvc configuration callback after the JsonApiDotNetCore callback as been executed.
+            _postConfigureMvcOptions?.Invoke(x);
+        });
+
+        ...
+    }
+
+    public void Configure(IApplicationBuilder app, IWebHostEnvironment environment)
+    {
+
+        ... 
+
+        // Using a callback, we can defer to later (when service collection has become available).
+        _postConfigureMvcOptions = mvcOptions =>
+        {
+            mvcOptions.Filters.Clear();
+            mvcOptions.Filters.Insert(0, app.ApplicationServices.GetService<CustomFilter>());
+        };
+
+        ...
+    }
+}
+```

docs/usage/resource-graph.md

@@ -10,31 +10,30 @@ It is built at app startup and available as a singleton through Dependency Injec
 
 There are three ways the resource graph can be created:
 
-1. Auto-discovery
+1. Manually specifying each resource
 2. Specifying an entire DbContext
-3. Manually specifying each resource
+3. Auto-discovery
 
-### Auto-Discovery
+It is also possible to combine the three of them at once. Be aware that some configuration might overlap, 
+for example you could manually add a resource to the graph which is also auto-discovered. In such a scenario, the configuration
+is prioritized by the order of the list above.
 
-Auto-discovery refers to the process of reflecting on an assembly and
-detecting all of the json:api resources and services.
+### Manual Specification
 
-The following command will build the resource graph using all `IIdentifiable`
-implementations. It also injects resource definitions and service layer overrides which we will
-cover in a later section. You can enable auto-discovery for the
-current assembly by adding the following to your `Startup` class.
+You can manually construct the graph.
 
 ```c#
 // Startup.cs
 public void ConfigureServices(IServiceCollection services)
 {
-    services.AddJsonApi(
-        options => { /* ... */ },
-        discovery => discovery.AddCurrentAssembly());
+    services.AddJsonApi(resources: builder =>
+    {
+        builder.AddResource<Person>();
+    });
 }
 ```
 
-### 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.
 
@@ -58,33 +57,60 @@ public void ConfigureServices(IServiceCollection services)
 }
 ```
 
-### Manual Specification
+### Auto-discovery
 
-You can also manually construct the graph.
+Auto-discovery refers to the process of reflecting on an assembly and
+detecting all of the json:api resources and services.
+
+The following command will build the resource graph using all `IIdentifiable`
+implementations. It also injects resource definitions and service layer overrides which we will
+cover in a later section. You can enable auto-discovery for the
+current assembly by adding the following to your `Startup` class.
 
 ```c#
 // Startup.cs
 public void ConfigureServices(IServiceCollection services)
 {
-    services.AddJsonApi(resources: builder =>
-    {
-        builder.AddResource<Person>();
-    });
+    services.AddJsonApi(
+        options => { /* ... */ },
+        discovery => discovery.AddCurrentAssembly());
 }
 ```
 
-### Public Resource Type Name
+### Public Resource Name
 
-The public resource type name is determined by the following criteria (in order of priority):
+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):
 
-1. The model is decorated with a `ResourceAttribute`
+1. The `publicName` option when manually adding a resource to the graph
 ```c#
-[Resource("my-models")]
+services.AddJsonApi(resources: builder =>
+{
+    builder.AddResource<Person>(publicName: "people");
+});
+```
+
+2. The model is decorated with a `ResourceAttribute`
+```c#
+[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 { /* ... */ }
 ```
+This convention can be changed by setting the `SerializerSettings` property on `IJsonApiOptions`.
+```c#
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddJsonApi(
+        options =>
+        {
+            options.SerializerSettings.ContractResolver = new DefaultContractResolver
+            {
+                NamingStrategy = new KebabCaseNamingStrategy()
+            }
+        });
+}
+```

docs/usage/routing.md

@@ -1,59 +1,69 @@
 # 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.
+The library will configure routes for each controller. By default, 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
+There are two ways the library will try to create a route for a controller:
+1. **By inspecting the controller for an associated resource**. The library will try to first use the public resource name of the resource associated to a controller. This means that the value of the `type` member of the json:api document for a resource will be equal to the route.
+Note that this implies that it is possible to configure a route configuring the exposed resource name. See [this section](~/usage/resource-graph.md#public-resource-name) on how this can be achieved. Example:
+```c#
+// controller
+public class MyResourceController : JsonApiController<MyApiResource> { /* .... */ } // note that the route is NOT "myResources", but "myApiResources"
 
-You can add a namespace to all URLs by specifying it in ConfigureServices
+// request
+GET /myApiResources HTTP/1.1
+
+// response
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
 
-```c#
-public void ConfigureServices(IServiceCollection services)
 {
-  services.AddJsonApi<AppDbContext>(
-      options => options.Namespace = "api/v1");
+  "data": [{
+    "type": "myApiResources",
+    "id": "1",
+    "attributes": { ... }
+  }]
 }
 ```
-Which results in URLs like: https://yourdomain.com/api/v1/people
-
-## Disable Convention
+2. **By using the name of the controller**. If no associated resource was detected for a controller, the library will construct a route from the name of the controller by using the configured naming strategy (*camelCase* by default, see [this section](~/usage/resource-graph.md#public-resource-name) on how to configure this). This is in alignment with the default .NET Core MVC routing approach. 
+In the following example the controller is not associated to a resource by the library because it does not inherit from `BaseJsonApiController<T>`.
+```c#
+// controller
+public class MyResourceController : ControllerBase { /* .... */ }
 
-You can disable the default casing convention and specify your own template by using the `DisableRoutingConvention` attribute.
+// request
+GET /myResources HTTP/1.1
+```
 
+## Customized the Routing Convention
+It is possible to fully customize routing behaviour by registering a `IJsonApiRoutingConvention` implementation.
 ```c#
-[Route("[controller]")]
-[DisableRoutingConvention]
-public class CamelCasedModelsController : JsonApiController<CamelCasedModel>
+// Startup.cs
+public void ConfigureServices(IServiceCollection services)
 {
-    public CamelCasedModelsController(
-        IJsonApiOptions options,
-        ILoggerFactory loggerFactory,
-        IResourceService<CamelCasedModel> resourceService)
-        : base(options, loggerFactory, resourceService)
-    { }
+    services.AddSingleton<IJsonApiConvention, CustomRoutingConvention>();
 }
 ```
 
-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.
+## Namespacing and Versioning URLs
+You can add a namespace to all URLs by specifying it in ConfigureServices
 
 ```c#
 public void ConfigureServices(IServiceCollection services)
 {
-    services.AddJsonApi(resources: builder =>
-        builder.AddResource<TodoItem>("my-models")); // kebab-cased
-}
-
-// controller definition
-[Route("api/my-models"), DisableRoutingConvention]
-public class MyModelsController : JsonApiController<TodoItem>
-{
-  //...
+  services.AddJsonApi<AppDbContext>(
+      options => options.Namespace = "api/v1");
 }
 ```
+Which results in URLs like: https://yourdomain.com/api/v1/people
 
-See [this](~/usage/resource-graph.md#public-resource-type-name) for
-more information on how the resource name is determined.
+## Disabling the Default Routing Convention
+It is possible to completely bypass the default routing convention for a particular controller and specify a custom routing template by using the `DisableRoutingConvention` attribute.
+In the following example, the `CamelCasedModel` resource can be accessed on `/my-custom-route`.
+
+```c#
+[Route("my-custom-route"), DisableRoutingConvention]
+public class MyCustomResourceController : JsonApiController<CamelCasedModel> { /* ... */ }
+```

src/Examples/JsonApiDotNetCoreExample/Startups/EmptyStartup.cs

@@ -2,6 +2,7 @@
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
 
 namespace JsonApiDotNetCoreExample
 {
@@ -11,16 +12,10 @@ namespace JsonApiDotNetCoreExample
     /// </summary>
     public abstract class EmptyStartup
     {
-        protected EmptyStartup(IConfiguration configuration)
-        {
-        }
+        protected EmptyStartup(IConfiguration configuration) { }
 
-        public virtual void ConfigureServices(IServiceCollection services)
-        {
-        }
+        public virtual void ConfigureServices(IServiceCollection services) { }
 
-        public virtual void Configure(IApplicationBuilder app, IWebHostEnvironment environment)
-        {
-        }
+        public virtual void Configure(IApplicationBuilder app, IWebHostEnvironment environment) { }
     }
 }

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/Examples/JsonApiDotNetCoreExample/Startups/TestStartup.cs

@@ -2,14 +2,13 @@
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
 
 namespace JsonApiDotNetCoreExample
 {
     public class TestStartup : Startup
     {
-        public TestStartup(IConfiguration configuration) : base(configuration)
-        {
-        }
+        public TestStartup(IConfiguration configuration) : base(configuration) { }
 
         protected override void ConfigureClock(IServiceCollection services)
         {

src/JsonApiDotNetCore/AssemblyInfo.cs

@@ -0,0 +1,7 @@
+using System.Runtime.CompilerServices;
+[assembly:InternalsVisibleTo("UnitTests")]
+[assembly:InternalsVisibleTo("DiscoveryTests")]
+[assembly:InternalsVisibleTo("JsonApiDotNetCoreExampleTests")]
+[assembly:InternalsVisibleTo("NoEntityFrameworkTests")]
+[assembly:InternalsVisibleTo("Benchmarks")]
+[assembly:InternalsVisibleTo("ResourceEntitySeparationExampleTests")]