Rewrite of LinkBuilder to use ASP.NET Core routing to render links (#987)

Rewrite of LinkBuilder to use ASP.NET Core routing to render links. The limitation that custom routes must end in the public resource name no longer applies.

- Fixed: Resource-level Self links in atomic:operations responses are now hidden when no controller exists for the resource type.
- Fixed: For determining which links to render, settings from primary resource were used on secondary endpoints. For example, if you configure Customer to show all links, but Orders no show none, then /customer/1/orders would show all links.
- Optimization: Compound `page[size]` parameter value (example: `10,articles:5`) is calculated once, instead of again for each pagination link.
- Deprecated: `IJsonApiRequest.BasePath`. This information is no longer needed, but we still set it for back-compat.
- Added support for non-standard route parameters in links, for example: `[DisableRoutingConvention, Route("{shopName}/products")]`

Author: Bart Koelman

docs/usage/routing.md

@@ -62,7 +62,7 @@ GET /orderLines HTTP/1.1
 It is possible to bypass the default routing convention for a controller.
 
 ```c#
-[Route("v1/custom/route/orderLines"), DisableRoutingConvention]
+[Route("v1/custom/route/lines-in-order"), DisableRoutingConvention]
 public class OrderLineController : JsonApiController<OrderLine>
 {
     public OrderLineController(IJsonApiOptions options, ILoggerFactory loggerFactory,
@@ -73,8 +73,6 @@ public class OrderLineController : JsonApiController<OrderLine>
 }
 ```
 
-It is required to match your custom url with the exposed name of the associated resource.
-
 ## Advanced Usage: Custom Routing Convention
 
 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`.

src/JsonApiDotNetCore/Middleware/IControllerResourceMapping.cs

@@ -8,8 +8,13 @@ namespace JsonApiDotNetCore.Middleware
     public interface IControllerResourceMapping
     {
         /// <summary>
-        /// Get the associated resource type for the provided controller type.
+        /// Gets the associated resource type for the provided controller type.
         /// </summary>
         Type GetResourceTypeForController(Type controllerType);
+
+        /// <summary>
+        /// Gets the associated controller name for the provided resource type.
+        /// </summary>
+        string GetControllerNameForResourceType(Type resourceType);
     }
 }

src/JsonApiDotNetCore/Middleware/IJsonApiRequest.cs

@@ -1,3 +1,4 @@
+using System;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Resources.Annotations;
 
@@ -22,6 +23,7 @@ public interface IJsonApiRequest
         /// Relative: /api/v1
         /// ]]></code>
         /// </example>
+        [Obsolete("This value is calculated for backwards compatibility, but it is no longer used and will be removed in a future version.")]
         string BasePath { get; }
 
         /// <summary>

src/JsonApiDotNetCore/Middleware/JsonApiRequest.cs

@@ -44,7 +44,9 @@ public void CopyFrom(IJsonApiRequest other)
             ArgumentGuard.NotNull(other, nameof(other));
 
             Kind = other.Kind;
+#pragma warning disable CS0618 // Type or member is obsolete
             BasePath = other.BasePath;
+#pragma warning restore CS0618 // Type or member is obsolete
             PrimaryId = other.PrimaryId;
             PrimaryResource = other.PrimaryResource;
             SecondaryResource = other.SecondaryResource;

src/JsonApiDotNetCore/Middleware/JsonApiRoutingConvention.cs

@@ -35,6 +35,7 @@ public class JsonApiRoutingConvention : IJsonApiRoutingConvention
         private readonly IResourceContextProvider _resourceContextProvider;
         private readonly Dictionary<string, string> _registeredControllerNameByTemplate = new Dictionary<string, string>();
         private readonly Dictionary<Type, ResourceContext> _resourceContextPerControllerTypeMap = new Dictionary<Type, ResourceContext>();
+        private readonly Dictionary<ResourceContext, ControllerModel> _controllerPerResourceContextMap = new Dictionary<ResourceContext, ControllerModel>();
 
         public JsonApiRoutingConvention(IJsonApiOptions options, IResourceContextProvider resourceContextProvider)
         {
@@ -58,6 +59,22 @@ public Type GetResourceTypeForController(Type controllerType)
             return null;
         }
 
+        /// <inheritdoc />
+        public string GetControllerNameForResourceType(Type resourceType)
+        {
+            ArgumentGuard.NotNull(resourceType, nameof(resourceType));
+
+            ResourceContext resourceContext = _resourceContextProvider.GetResourceContext(resourceType);
+
+            if (_controllerPerResourceContextMap.TryGetValue(resourceContext, out ControllerModel controllerModel))
+
+            {
+                return controllerModel.ControllerName;
+            }
+
+            return null;
+        }
+
         /// <inheritdoc />
         public void Apply(ApplicationModel application)
         {
@@ -78,6 +95,7 @@ public void Apply(ApplicationModel application)
                         if (resourceContext != null)
                         {
                             _resourceContextPerControllerTypeMap.Add(controller.ControllerType, resourceContext);
+                            _controllerPerResourceContextMap.Add(resourceContext, controller);
                         }
                     }
                 }
@@ -117,9 +135,7 @@ private string TemplateFromResource(ControllerModel model)
         {
             if (_resourceContextPerControllerTypeMap.TryGetValue(model.ControllerType, out ResourceContext resourceContext))
             {
-                string template = $"{_options.Namespace}/{resourceContext.PublicName}";
-
-                return template;
+                return $"{_options.Namespace}/{resourceContext.PublicName}";
             }
 
             return null;
@@ -131,9 +147,7 @@ private string TemplateFromResource(ControllerModel model)
         private string TemplateFromController(ControllerModel model)
         {
             string controllerName = _options.SerializerNamingStrategy.GetPropertyName(model.ControllerName, false);
-            string template = $"{_options.Namespace}/{controllerName}";
-
-            return template;
+            return $"{_options.Namespace}/{controllerName}";
         }
 
         /// <summary>