Public API surface (#808)

* Renamed generic type parameter T to TResource

* Fixed inconsistencies in generic type parameter constraints

* Reviewed collection usage

Reviewed generic IEnumerable usage in public signatures (fixes 'Possible multiple enumeration' warning)
Reviewed usage of generic List and Dictionary in public signatures
Removed redundant ToList/ToArray/AsReadOnly calls
Replaced ToList() with ToArray(), which uses a bit more memory but is faster

* Renamed CurrentRequest to JsonApiRequest ('current' is vague terminology)

* Merged AssemblyInfo.cs versions and removed unneeded InternalsVisibleTo

* Reorganized namespaces
Moved types into separate files (and fixed filename mismatches)
Unified TypeHelper and TypeExtensions (inlined methods with single usage)

* Fixes in documentation generation. Removed the parts from .csproj because it does not work correctly -- it looks like something from before moving to /docs.

* Code cleanup: removed redundant parentheses

* Code cleanup: spelling errors

* Code cleanup: removed redundant qualifiers

* Code cleanup: removed redundant cast

* Fixed: possible comparison of value type with null
Removed invalid inheritdoc

* Fixup naming conventions to match with existing style
Culture-sensitive string comparions

* Use null instead of empty string for default value of TId; removed hack for GUIDs

* Renamed IJsonApiOptions parameter on controllers for consistency with other places

* Trace logging: shorter syntax and improved performance

* Added null checks on input parameters of exposed methods

* Removed invalid usage of inheritdoc

* Opened up more for extensibility

* Extract method

* Normalized spacing in inheritdoc tags

* Reviewed doc-comments

* Moved controller attributes in sub-namespace

* Cleanup usings

* Moved client serialization into Internal sub-namespace

Author: Bart Koelman

Directory.Build.props

@@ -1,7 +1,6 @@
 <Project>
   <PropertyGroup>
     <NetCoreAppVersion>netcoreapp3.1</NetCoreAppVersion>
-    <NetStandardVersion>netstandard2.1</NetStandardVersion>
     <AspNetCoreVersion>3.1.*</AspNetCoreVersion>
     <EFCoreVersion>3.1.*</EFCoreVersion>
     <NpgsqlPostgreSQLVersion>3.1.*</NpgsqlPostgreSQLVersion>
@@ -10,6 +9,7 @@
   <PropertyGroup Condition="'$(Configuration)'=='Release'">
     <NoWarn>$(NoWarn);1591</NoWarn>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
   <!-- Test Project Dependencies -->

README.md

@@ -54,10 +54,10 @@ public class Article : Identifiable
 public class ArticlesController : JsonApiController<Article>
 {
         public ArticlesController(
-            IJsonApiOptions jsonApiOptions,
+            IJsonApiOptions options,
             IResourceService<Article> resourceService,
             ILoggerFactory loggerFactory)
-            : base(jsonApiOptions, resourceService, loggerFactory)
+            : base(options, resourceService, loggerFactory)
         { }
 }
 ```

benchmarks/BenchmarkResource.cs

@@ -1,11 +1,11 @@
-using JsonApiDotNetCore.Models;
-using JsonApiDotNetCore.Models.Annotation;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
 
 namespace Benchmarks
 {
     public sealed class BenchmarkResource : Identifiable
     {
-        [Attr(BenchmarkResourcePublicNames.NameAttr)] 
+        [Attr(PublicName = BenchmarkResourcePublicNames.NameAttr)] 
         public string Name { get; set; }
 
         [HasOne]

benchmarks/DependencyFactory.cs

@@ -1,9 +1,6 @@
 using System;
-using JsonApiDotNetCore.Builders;
 using JsonApiDotNetCore.Configuration;
-using JsonApiDotNetCore.Internal.Contracts;
-using JsonApiDotNetCore.Models;
-using JsonApiDotNetCore.Services.Contract;
+using JsonApiDotNetCore.Resources;
 using Microsoft.Extensions.Logging.Abstractions;
 using Moq;
 
@@ -14,7 +11,7 @@ internal static class DependencyFactory
         public static IResourceGraph CreateResourceGraph(IJsonApiOptions options)
         {
             IResourceGraphBuilder builder = new ResourceGraphBuilder(options, NullLoggerFactory.Instance);
-            builder.AddResource<BenchmarkResource>(BenchmarkResourcePublicNames.Type);
+            builder.Add<BenchmarkResource>(BenchmarkResourcePublicNames.Type);
             return builder.Build();
         }
 

benchmarks/LinkBuilder/LinkBuilderGetNamespaceFromPathBenchmarks.cs

@@ -1,6 +1,6 @@
-using BenchmarkDotNet.Attributes;
 using System;
 using System.Text;
+using BenchmarkDotNet.Attributes;
 
 namespace Benchmarks.LinkBuilder
 {

benchmarks/Query/QueryParserBenchmarks.cs

@@ -3,11 +3,10 @@
 using System.ComponentModel.Design;
 using BenchmarkDotNet.Attributes;
 using JsonApiDotNetCore.Configuration;
-using JsonApiDotNetCore.Internal;
-using JsonApiDotNetCore.Internal.Contracts;
-using JsonApiDotNetCore.Internal.QueryStrings;
+using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.QueryStrings;
-using JsonApiDotNetCore.RequestServices;
+using JsonApiDotNetCore.QueryStrings.Internal;
+using JsonApiDotNetCore.Resources;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.WebUtilities;
 using Microsoft.Extensions.Logging.Abstractions;
@@ -30,20 +29,19 @@ public QueryParserBenchmarks()
 
             IResourceGraph resourceGraph = DependencyFactory.CreateResourceGraph(options);
 
-            var currentRequest = new CurrentRequest
+            var request = new JsonApiRequest
             {
                 PrimaryResource = resourceGraph.GetResourceContext(typeof(BenchmarkResource))
             };
 
-            _queryStringReaderForSort = CreateQueryParameterDiscoveryForSort(resourceGraph, currentRequest, options, _queryStringAccessor);
-            _queryStringReaderForAll = CreateQueryParameterDiscoveryForAll(resourceGraph, currentRequest, options, _queryStringAccessor);
+            _queryStringReaderForSort = CreateQueryParameterDiscoveryForSort(resourceGraph, request, options, _queryStringAccessor);
+            _queryStringReaderForAll = CreateQueryParameterDiscoveryForAll(resourceGraph, request, options, _queryStringAccessor);
         }
 
         private static QueryStringReader CreateQueryParameterDiscoveryForSort(IResourceGraph resourceGraph,
-            CurrentRequest currentRequest,
-            IJsonApiOptions options, FakeRequestQueryStringAccessor queryStringAccessor)
+            JsonApiRequest request, IJsonApiOptions options, FakeRequestQueryStringAccessor queryStringAccessor)
         {
-            var sortReader = new SortQueryStringParameterReader(currentRequest, resourceGraph);
+            var sortReader = new SortQueryStringParameterReader(request, resourceGraph);
 
             var readers = new List<IQueryStringParameterReader>
             {
@@ -54,14 +52,14 @@ private static QueryStringReader CreateQueryParameterDiscoveryForSort(IResourceG
         }
 
         private static QueryStringReader CreateQueryParameterDiscoveryForAll(IResourceGraph resourceGraph,
-            CurrentRequest currentRequest, IJsonApiOptions options, FakeRequestQueryStringAccessor queryStringAccessor)
+            JsonApiRequest request, IJsonApiOptions options, FakeRequestQueryStringAccessor queryStringAccessor)
         {
             var resourceFactory = new ResourceFactory(new ServiceContainer());
 
-            var filterReader = new FilterQueryStringParameterReader(currentRequest, resourceGraph, resourceFactory, options);
-            var sortReader = new SortQueryStringParameterReader(currentRequest, resourceGraph);
-            var sparseFieldSetReader = new SparseFieldSetQueryStringParameterReader(currentRequest, resourceGraph);
-            var paginationReader = new PaginationQueryStringParameterReader(currentRequest, resourceGraph, options);
+            var filterReader = new FilterQueryStringParameterReader(request, resourceGraph, resourceFactory, options);
+            var sortReader = new SortQueryStringParameterReader(request, resourceGraph);
+            var sparseFieldSetReader = new SparseFieldSetQueryStringParameterReader(request, resourceGraph);
+            var paginationReader = new PaginationQueryStringParameterReader(request, resourceGraph, options);
             var defaultsReader = new DefaultsQueryStringParameterReader(options);
             var nullsReader = new NullsQueryStringParameterReader(options);
 

benchmarks/Serialization/JsonApiDeserializerBenchmarks.cs

@@ -3,11 +3,9 @@
 using System.ComponentModel.Design;
 using BenchmarkDotNet.Attributes;
 using JsonApiDotNetCore.Configuration;
-using JsonApiDotNetCore.Internal;
-using JsonApiDotNetCore.Internal.Contracts;
-using JsonApiDotNetCore.Models;
+using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Serialization;
-using JsonApiDotNetCore.Serialization.Server;
+using JsonApiDotNetCore.Serialization.Objects;
 using Microsoft.AspNetCore.Http;
 using Newtonsoft.Json;
 

benchmarks/Serialization/JsonApiSerializerBenchmarks.cs

@@ -1,13 +1,11 @@
 using System;
 using BenchmarkDotNet.Attributes;
 using JsonApiDotNetCore.Configuration;
-using JsonApiDotNetCore.Internal.Contracts;
-using JsonApiDotNetCore.Internal.QueryStrings;
+using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.Queries;
-using JsonApiDotNetCore.RequestServices;
+using JsonApiDotNetCore.QueryStrings.Internal;
 using JsonApiDotNetCore.Serialization;
-using JsonApiDotNetCore.Serialization.Server;
-using JsonApiDotNetCore.Serialization.Server.Builders;
+using JsonApiDotNetCore.Serialization.Building;
 using Moq;
 
 namespace Benchmarks.Serialization
@@ -41,11 +39,11 @@ public JsonApiSerializerBenchmarks()
 
         private static FieldsToSerialize CreateFieldsToSerialize(IResourceGraph resourceGraph)
         {
-            var currentRequest = new CurrentRequest();
+            var request = new JsonApiRequest();
 
             var constraintProviders = new IQueryConstraintProvider[]
             {
-                new SparseFieldSetQueryStringParameterReader(currentRequest, resourceGraph)
+                new SparseFieldSetQueryStringParameterReader(request, resourceGraph)
             };
 
             var resourceDefinitionProvider = DependencyFactory.CreateResourceDefinitionProvider(resourceGraph);

docs/api/index.md

@@ -5,5 +5,5 @@ This section documents the package API and is generated from the XML source comm
 ## Common APIs
 
 - [`JsonApiOptions`](JsonApiDotNetCore.Configuration.JsonApiOptions.yml)
-- [`IResourceGraph`](JsonApiDotNetCore.Internal.Contracts.IResourceGraph.yml)
-- [`ResourceDefinition<TResource>`](JsonApiDotNetCore.Models.ResourceDefinition-1.yml)
+- [`IResourceGraph`](JsonApiDotNetCore.Configuration.IResourceGraph.yml)
+- [`ResourceDefinition<TResource>`](JsonApiDotNetCore.Resources.ResourceDefinition-1.yml)

docs/docfx.json

@@ -10,7 +10,7 @@
             "dest": "api",
             "disableGitFeatures": false,
             "properties": {
-                "targetFramework": "netstandard2.0"
+                "targetFramework": "netcoreapp3.1"
             }
         }
     ],

docs/getting-started/step-by-step.md

@@ -68,10 +68,10 @@ where `T` is the model that inherits from `Identifiable<TId>`
 public class PeopleController : JsonApiController<Person>
 {
     public PeopleController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         IResourceService<Person> resourceService)
-    : base(jsonApiOptions, loggerFactory, resourceService)
+    : base(options, loggerFactory, resourceService)
     { }
 }
 ```

docs/usage/extensibility/controllers.md

@@ -6,10 +6,10 @@ You need to create controllers that inherit from `JsonApiController<T>`
 public class ArticlesController : JsonApiController<Article>
 {
     public ArticlesController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         IResourceService<Article> resourceService)
-        : base(jsonApiOptions, loggerFactory, resourceService)
+        : base(options, loggerFactory, resourceService)
     { }
 }
 ```
@@ -23,11 +23,11 @@ public class ArticlesController : JsonApiController<Article, Guid>
 //---------------------------------------------------------- ^^^^
 {
     public ArticlesController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         IResourceService<Article, Guid> resourceService)
         //----------------------- ^^^^
-        : base(jsonApiOptions, loggerFactory, resourceService)
+        : base(options, loggerFactory, resourceService)
     { }
 }
 ```
@@ -44,10 +44,10 @@ This approach is ok, but introduces some boilerplate that can easily be avoided.
 public class ArticlesController : BaseJsonApiController<Article>
 {
     public ArticlesController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         IResourceService<Article> resourceService)
-        : base(jsonApiOptions, loggerFactory, resourceService)
+        : base(options, loggerFactory, resourceService)
     { }
 
     [HttpGet]
@@ -81,10 +81,10 @@ An attempt to use one blacklisted methods will result in a HTTP 405 Method Not A
 public class ArticlesController : BaseJsonApiController<Article>
 {
     public ArticlesController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         IResourceService<Article> resourceService)
-        : base(jsonApiOptions, loggerFactory, resourceService)
+        : base(options, loggerFactory, resourceService)
     { }
 }
 ```
@@ -101,10 +101,10 @@ For more information about resource injection, see the next section titled Resou
 public class ReportsController : BaseJsonApiController<Report>
 {
     public ReportsController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         IResourceService<Report> resourceService)
-        : base(jsonApiOptions, loggerFactory, resourceService)
+        : base(options, loggerFactory, resourceService)
     { }
 
     [HttpGet]

docs/usage/extensibility/services.md

@@ -148,11 +148,11 @@ Then in the controller, you should inherit from the base controller and pass the
 public class ArticlesController : BaseJsonApiController<Article>
 {
     public ArticlesController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         ICreateService<Article, int> create,
         IDeleteService<Article, int> delete)
-        : base(jsonApiOptions, loggerFactory, create: create, delete: delete)
+        : base(options, loggerFactory, create: create, delete: delete)
     { }
 
     [HttpPost]

docs/usage/routing.md

@@ -30,10 +30,10 @@ You can disable the default casing convention and specify your own template by u
 public class CamelCasedModelsController : JsonApiController<CamelCasedModel>
 {
     public CamelCasedModelsController(
-        IJsonApiOptions jsonApiOptions,
+        IJsonApiOptions options,
         ILoggerFactory loggerFactory,
         IResourceService<CamelCasedModel> resourceService)
-        : base(jsonApiOptions, loggerFactory, resourceService)
+        : base(options, loggerFactory, resourceService)
     { }
 }
 ```

src/Examples/GettingStarted/Controllers/ArticlesController.cs

@@ -9,10 +9,10 @@ namespace GettingStarted.Controllers
     public sealed class ArticlesController : JsonApiController<Article>
     {
         public ArticlesController(
-            IJsonApiOptions jsonApiOptions,
+            IJsonApiOptions options,
             ILoggerFactory loggerFactory,
             IResourceService<Article> resourceService)
-            : base(jsonApiOptions, loggerFactory, resourceService)
+            : base(options, loggerFactory, resourceService)
         { }
     }
 }

src/Examples/GettingStarted/Controllers/PeopleController.cs

@@ -9,10 +9,10 @@ namespace GettingStarted.Controllers
     public sealed class PeopleController : JsonApiController<Person>
     {
         public PeopleController(
-            IJsonApiOptions jsonApiOptions,
+            IJsonApiOptions options,
             ILoggerFactory loggerFactory,
             IResourceService<Person> resourceService)
-            : base(jsonApiOptions, loggerFactory, resourceService)
+            : base(options, loggerFactory, resourceService)
         { }
     }
 }

src/Examples/GettingStarted/Models/Article.cs

@@ -1,5 +1,5 @@
-using JsonApiDotNetCore.Models;
-using JsonApiDotNetCore.Models.Annotation;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
 
 namespace GettingStarted.Models
 {

src/Examples/GettingStarted/Models/Person.cs

@@ -1,6 +1,6 @@
 using System.Collections.Generic;
-using JsonApiDotNetCore.Models;
-using JsonApiDotNetCore.Models.Annotation;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
 
 namespace GettingStarted.Models
 {

src/Examples/GettingStarted/Startup.cs

@@ -1,6 +1,6 @@
 using GettingStarted.Data;
 using GettingStarted.Models;
-using JsonApiDotNetCore;
+using JsonApiDotNetCore.Configuration;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.DependencyInjection;

src/Examples/JsonApiDotNetCoreExample/Controllers/ArticlesController.cs

@@ -9,10 +9,10 @@ namespace JsonApiDotNetCoreExample.Controllers
     public sealed class ArticlesController : JsonApiController<Article>
     {
         public ArticlesController(
-            IJsonApiOptions jsonApiOptions,
+            IJsonApiOptions options,
             ILoggerFactory loggerFactory,
             IResourceService<Article> resourceService)
-            : base(jsonApiOptions, loggerFactory, resourceService)
+            : base(options, loggerFactory, resourceService)
         { }
     }
 }

src/Examples/JsonApiDotNetCoreExample/Controllers/AuthorsController.cs

@@ -9,10 +9,10 @@ namespace JsonApiDotNetCoreExample.Controllers
     public sealed class AuthorsController : JsonApiController<Author>
     {
         public AuthorsController(
-            IJsonApiOptions jsonApiOptions,
+            IJsonApiOptions options,
             ILoggerFactory loggerFactory,
             IResourceService<Author> resourceService)
-            : base(jsonApiOptions, loggerFactory, resourceService)
+            : base(options, loggerFactory, resourceService)
         { }
     }
 }

src/Examples/JsonApiDotNetCoreExample/Controllers/BlogsController.cs

@@ -9,10 +9,10 @@ namespace JsonApiDotNetCoreExample.Controllers
     public sealed class BlogsController : JsonApiController<Blog>
     {
         public BlogsController(
-            IJsonApiOptions jsonApiOptions,
+            IJsonApiOptions options,
             ILoggerFactory loggerFactory,
             IResourceService<Blog> resourceService)
-            : base(jsonApiOptions, loggerFactory, resourceService)
+            : base(options, loggerFactory, resourceService)
         { }
     }
 }