docs: update routing related docs

Author: maurei

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,61 @@ 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 in the json:api payload as the `type` member. 
+How this is exposed can be configured in with the following approaches (in order of priority):
 
-1. The model is decorated with a `ResourceAttribute`
+1. The `publicResourceName` option when manually adding a resource to the graph
 ```c#
-[Resource("my-models")]
+services.AddJsonApi(resources: builder =>
+{
+    builder.AddResource<Person>(publicResourceName: "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,14 +1,55 @@
 # 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.
+For example: 
+```c#
+// controller
+public class MyResourceController : JsonApiController<MyApiResource> { /* .... */ }
+
+// request
+GET /myApiResources HTTP/1.1
+
+// response
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": [{
+    "type": "myApiResources",
+    "id": "1",
+    "attributes": { ... }
+  }]
+}
+```
+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).
+In the following example the controller does not inherit from `BaseJsonApiController<T>` and the library is unable associate a resource to it.
+```c#
+// controller
+public class MyResourceController : ControllerBase { /* .... */ }
+
+// request
+GET /myResources HTTP/1.1
+```
 
+## Customized the Routing Convention
+It is possible to fully customize routing behaviour by registering a `IJsonApiRoutingConvention` implementation **before** calling `AddJsonApi( ... )`.
+```c#
+// Startup.cs
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddSingleton<IJsonApiConvention, CustomRoutingConvention>();
+    services.AddJsonApi( /* ... */ );
+}
+```
+
+## Namespacing and Versioning URLs
 You can add a namespace to all URLs by specifying it in ConfigureServices
 
 ```c#
@@ -20,40 +61,20 @@ public void ConfigureServices(IServiceCollection services)
 ```
 Which results in URLs like: https://yourdomain.com/api/v1/people
 
-## Disable Convention
-
-You can disable the default casing convention and specify your own template by using the `DisableRoutingConvention` attribute.
+## 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 `/myCustomResources` (assuming that the default naming strategy is used).
 
 ```c#
 [Route("[controller]")]
 [DisableRoutingConvention]
-public class CamelCasedModelsController : JsonApiController<CamelCasedModel>
+public class MyCustomResourceController : JsonApiController<CamelCasedModel>
 {
-    public CamelCasedModelsController(
+    public MyCustomResourceController(
         IJsonApiOptions jsonApiOptions,
         ILoggerFactory loggerFactory,
         IResourceService<CamelCasedModel> resourceService)
         : base(jsonApiOptions, loggerFactory, resourceService)
     { }
 }
 ```
-
-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.
-
-```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>
-{
-  //...
-}
-```
-
-See [this](~/usage/resource-graph.md#public-resource-type-name) for
-more information on how the resource name is determined.

src/JsonApiDotNetCore/Builders/JsonApiApplicationBuilder.cs

@@ -97,8 +97,8 @@ public void ConfigureMvc()
         public void AddResourceGraph(Type dbContextType, Action<IResourceGraphBuilder> configureResources)
         {
             using var intermediateProvider = _services.BuildServiceProvider();
-            AddResourcesFromDbContext(dbContextType, intermediateProvider, _resourceGraphBuilder);
             AutoDiscoverResources(_serviceDiscoveryFacade);
+            AddResourcesFromDbContext(dbContextType, intermediateProvider, _resourceGraphBuilder);
             UserConfigureResources(configureResources, _resourceGraphBuilder);
             _services.AddSingleton(_resourceGraphBuilder.Build());
         }