chore: finishing touches comments serialization

Author: maurei

src/JsonApiDotNetCore/Data/DefaultEntityRepository.cs

@@ -13,6 +13,7 @@
 using JsonApiDotNetCore.Serialization;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging;
+
 namespace JsonApiDotNetCore.Data
 {
     /// <summary>

src/JsonApiDotNetCore/DependencyInjection/ServiceLocator.cs

@@ -218,7 +218,7 @@ public static void AddJsonApiInternals(
             services.AddScoped<IFieldsToSerialize, FieldsToSerialize>();
 
             AddServerSerialization(services);
-            AddClientSerialization(services);
+
             if (jsonApiOptions.EnableResourceHooks)
                 AddResourceHooks(services);
 
@@ -244,11 +244,15 @@ private static void AddServerSerialization(IServiceCollection services)
             services.AddScoped(typeof(IMetaBuilder<>), typeof(MetaBuilder<>));
             services.AddScoped(typeof(ResponseSerializer<>));
             services.AddScoped(sp => sp.GetRequiredService<IJsonApiSerializerFactory>().GetSerializer());
-
             services.AddScoped<IResourceObjectBuilder, ResponseResourceObjectBuilder>();
         }
 
-        private static void AddClientSerialization(IServiceCollection services)
+        /// <summary>
+        /// Enables client serializers for sending requests and receiving responses
+        /// in json:api format. Internally only used for testing.
+        /// Will be extended in the future to be part of a JsonApiClientDotNetCore package.
+        /// </summary>
+        public static void AddClientSerialization(this IServiceCollection services)
         {
             services.AddScoped<IResponseDeserializer, ResponseDeserializer>();
 

src/JsonApiDotNetCore/Extensions/IServiceCollectionExtensions.cs

@@ -12,7 +12,7 @@ namespace JsonApiDotNetCore.Formatters
     /// <summary>
     /// Formats the response data used  https://docs.microsoft.com/en-us/aspnet/core/web-api/advanced/formatting?view=aspnetcore-3.0.
     /// It was intended to have as little dependencies as possible in formatting layer for greater extensibility.
-    /// It onls depends on <see cref="IJsonApiSerializerFactory"/>.
+    /// It onls depends on <see cref="IJsonApiSerializer"/>.
     /// </summary>
     public class JsonApiWriter : IJsonApiWriter
     {

src/JsonApiDotNetCore/Formatters/JsonApiWriter.cs

@@ -55,11 +55,6 @@
     <Folder Include="Serialization\Server\Builders\" />
     <Folder Include="Query\Contracts\" />
     <Folder Include="Query\Common\" />
-  </ItemGroup>
-  <ItemGroup>
-    <Compile Remove="Serialization\Client\RequestResourceObjectBuilder.cs" />
-  </ItemGroup>
-  <ItemGroup>
-    <None Include="Serialization\Client\RequestResourceObjectBuilder.cs" Condition=" '$(EnableDefaultCompileItems)' == 'true' " />
+    <Folder Include="Serialization\Server\Contracts\" />
   </ItemGroup>
 </Project>

src/JsonApiDotNetCore/JsonApiDotNetCore.csproj

@@ -3,7 +3,6 @@
 using System.Threading.Tasks;
 using JsonApiDotNetCore.Internal;
 using JsonApiDotNetCore.Managers.Contracts;
-using JsonApiDotNetCore.Services;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.Primitives;

src/JsonApiDotNetCore/Middleware/RequestMiddleware.cs

@@ -9,11 +9,8 @@
 
 namespace JsonApiDotNetCore.Serialization.Client
 {
-
     /// <summary>
     /// Client serializer implementation of <see cref="BaseDocumentBuilder"/>
-    /// Note that this implementation does not override the default implementation
-    /// of <see cref="ResourceObjectBuilder.GetRelationshipData"/>.
     /// </summary>
     public class RequestSerializer : BaseDocumentBuilder, IRequestSerializer
     {

src/JsonApiDotNetCore/Serialization/Client/IRequestResourceObjectBuilder.cs

@@ -6,8 +6,8 @@
 namespace JsonApiDotNetCore.Serialization
 {
     /// <summary>
-    /// Abstract base class for serialization that extends <see cref="ResourceObjectBuilder"/>.
-    /// Converts entities in to <see cref="ResourceObject"/>s and wraps them in a <see cref="Document"/>.
+    /// Abstract base class for serialization.
+    /// Uses <see cref="IResourceObjectBuilder"/> to convert entities in to <see cref="ResourceObject"/>s and wraps them in a <see cref="Document"/>.
     /// </summary>
     public abstract class BaseDocumentBuilder
     {

src/JsonApiDotNetCore/Serialization/Client/RequestResourceObjectBuilder.cs

@@ -4,7 +4,7 @@
 namespace JsonApiDotNetCore.Serialization
 {
     /// <summary>
-    /// Abstract base class for serialization. Converts entities in to <see cref="ResourceObject"/>s
+    /// Responsible for converting entities in to <see cref="ResourceObject"/>s
     /// given a list of attributes and relationships.
     /// </summary> 
     public interface IResourceObjectBuilder

src/JsonApiDotNetCore/Serialization/Client/RequestSerializer.cs

@@ -9,10 +9,7 @@
 namespace JsonApiDotNetCore.Serialization
 {
 
-    /// <summary>
-    /// Abstract base class for serialization. Converts entities in to <see cref="ResourceObject"/>s
-    /// given a list of attributes and relationships.
-    /// </summary>
+    /// <inheritdoc/> 
     public class ResourceObjectBuilder : IResourceObjectBuilder
     {
         protected readonly IResourceGraph _resourceGraph;
@@ -27,14 +24,7 @@ public ResourceObjectBuilder(IResourceGraph resourceGraph, IContextEntityProvide
             _settings = settings;
         }
 
-        /// <summary>
-        /// Converts <paramref name="entity"/> into a <see cref="ResourceObject"/>.
-        /// Adds the attributes and relationships that are enlisted in <paramref name="attributes"/> and <paramref name="relationships"/>
-        /// </summary>
-        /// <param name="entity">Entity to build a Resource Object for</param>
-        /// <param name="attributes">Attributes to include in the building process</param>
-        /// <param name="relationships">Relationships to include in the building process</param>
-        /// <returns>The resource object that was built</returns>
+        /// <inheritdoc/> 
         public ResourceObject Build(IIdentifiable entity, IEnumerable<AttrAttribute> attributes = null, IEnumerable<RelationshipAttribute> relationships = null)
         {
             var resourceContext = _provider.GetContextEntity(entity.GetType());
@@ -53,30 +43,6 @@ public ResourceObject Build(IIdentifiable entity, IEnumerable<AttrAttribute> att
             return ro;
         }
 
-        private void ProcessRelationships(IIdentifiable entity, IEnumerable<RelationshipAttribute> relationships, ResourceObject ro)
-        {
-            foreach (var rel in relationships)
-            {
-                var relData = GetRelationshipData(rel, entity);
-                if (relData != null)
-                    (ro.Relationships = ro.Relationships ?? new Dictionary<string, RelationshipEntry>()).Add(rel.PublicRelationshipName, relData);
-            }
-        }
-
-        private void ProcessAttributes(IIdentifiable entity, IEnumerable<AttrAttribute> attributes, ResourceObject ro)
-        {
-            ro.Attributes = new Dictionary<string, object>();
-            foreach (var attr in attributes)
-                AddAttribute(entity, ro, attr);
-        }
-
-        private void AddAttribute(IIdentifiable entity, ResourceObject ro, AttrAttribute attr)
-        {
-            var value = attr.GetValue(entity);
-            if (!(value == default && _settings.OmitDefaultValuedAttributes) && !(value == null && _settings.OmitDefaultValuedAttributes))
-                ro.Attributes.Add(attr.PublicAttributeName, value);
-        }
-
         /// <summary>
         /// Builds the <see cref="RelationshipEntry"/> entries of the "relationships
         /// objects" The default behaviour is to just construct a resource linkage
@@ -89,6 +55,9 @@ protected virtual RelationshipEntry GetRelationshipData(RelationshipAttribute re
             return new RelationshipEntry { Data = GetRelatedResourceLinkage(relationship, entity) };
         }
 
+        /// <summary>
+        /// Gets the value for the <see cref="RelationshipEntry.Data"/> property.
+        /// </summary>
         protected object GetRelatedResourceLinkage(RelationshipAttribute relationship, IIdentifiable entity)
         {
             if (relationship is HasOneAttribute hasOne)
@@ -150,5 +119,32 @@ private bool IsRequiredToOneRelationship(HasOneAttribute attr, IIdentifiable ent
 
             return false;
         }
+
+        /// <summary>
+        /// Puts the relationships of the entity into the resource object.
+        /// </summary>
+        private void ProcessRelationships(IIdentifiable entity, IEnumerable<RelationshipAttribute> relationships, ResourceObject ro)
+        {
+            foreach (var rel in relationships)
+            {
+                var relData = GetRelationshipData(rel, entity);
+                if (relData != null)
+                    (ro.Relationships = ro.Relationships ?? new Dictionary<string, RelationshipEntry>()).Add(rel.PublicRelationshipName, relData);
+            }
+        }
+
+        /// <summary>
+        /// Puts the attributes of the entity into the resource object.
+        /// </summary>
+        private void ProcessAttributes(IIdentifiable entity, IEnumerable<AttrAttribute> attributes, ResourceObject ro)
+        {
+            ro.Attributes = new Dictionary<string, object>();
+            foreach (var attr in attributes)
+            {
+                var value = attr.GetValue(entity);
+                if (!(value == default && _settings.OmitDefaultValuedAttributes) && !(value == null && _settings.OmitDefaultValuedAttributes))
+                    ro.Attributes.Add(attr.PublicAttributeName, value);
+            }
+        }
     }
 }

src/JsonApiDotNetCore/Serialization/Common/DocumentBuilder.cs

@@ -1,3 +1,4 @@
+using JsonApiDotNetCore.Extensions;
 using JsonApiDotNetCore.Services;
 using JsonApiDotNetCoreExample;
 using Microsoft.AspNetCore.Hosting;
@@ -15,6 +16,7 @@ public TestStartup(IHostingEnvironment env) : base(env)
         public override IServiceProvider ConfigureServices(IServiceCollection services)
         {
             base.ConfigureServices(services);
+            services.AddClientSerialization();
             services.AddScoped<IScopedServiceProvider, TestScopedServiceProvider>();
             return services.BuildServiceProvider();
         }