use IResourceNameFormatter in ContextGraph

add documentation

Author: jaredcnance

src/JsonApiDotNetCore/Builders/ContextGraphBuilder.cs

@@ -48,6 +48,12 @@ public interface IContextGraphBuilder
         /// <typeparam name="T">The <see cref="DbContext"/> implementation type.</typeparam>
         IContextGraphBuilder AddDbContext<T>() where T : DbContext;
 
+        /// <summary>
+        /// Specify the <see cref="IResourceNameFormatter"/> used to format resource names.
+        /// </summary>
+        /// <param name="resourceNameFormatter">Formatter used to define exposed resource names by convention.</param>
+        IContextGraphBuilder UseNameFormatter(IResourceNameFormatter resourceNameFormatter);
+
         /// <summary>
         /// Which links to include. Defaults to <see cref="Link.All"/>.
         /// </summary>
@@ -60,6 +66,8 @@ public class ContextGraphBuilder : IContextGraphBuilder
         private List<ValidationResult> _validationResults = new List<ValidationResult>();
 
         private bool _usesDbContext;
+        private IResourceNameFormatter _resourceNameFormatter = new DefaultResourceNameFormatter();
+
         public Link DocumentLinks { get; set; } = Link.All;
 
         public IContextGraph Build()
@@ -71,12 +79,15 @@ public IContextGraph Build()
             return graph;
         }
 
+        /// <inheritdoc />
         public IContextGraphBuilder AddResource<TResource>(string pluralizedTypeName) where TResource : class, IIdentifiable<int>
             => AddResource<TResource, int>(pluralizedTypeName);
 
+        /// <inheritdoc />
         public IContextGraphBuilder AddResource<TResource, TId>(string pluralizedTypeName) where TResource : class, IIdentifiable<TId>
             => AddResource(typeof(TResource), typeof(TId), pluralizedTypeName);
 
+        /// <inheritdoc />
         public IContextGraphBuilder AddResource(Type entityType, Type idType, string pluralizedTypeName)
         {
             AssertEntityIsNotAlreadyDefined(entityType);
@@ -152,6 +163,7 @@ protected virtual Type GetRelationshipType(RelationshipAttribute relation, Prope
 
         private Type GetResourceDefinitionType(Type entityType) => typeof(ResourceDefinition<>).MakeGenericType(entityType);
 
+        /// <inheritdoc />
         public IContextGraphBuilder AddDbContext<T>() where T : DbContext
         {
             _usesDbContext = true;
@@ -174,14 +186,14 @@ public IContextGraphBuilder AddDbContext<T>() where T : DbContext
                     var (isJsonApiResource, idType) = GetIdType(entityType);
 
                     if (isJsonApiResource)
-                        _entities.Add(GetEntity(GetResourceName(property, entityType), entityType, idType));
+                        _entities.Add(GetEntity(GetResourceNameFromDbSetProperty(property, entityType), entityType, idType));
                 }
             }
 
             return this;
         }
 
-        private string GetResourceName(PropertyInfo property, Type resourceType)
+        private string GetResourceNameFromDbSetProperty(PropertyInfo property, Type resourceType)
         {
             // check the class definition first
             // [Resource("models"] public class Model : Identifiable { /* ... */ }
@@ -194,7 +206,7 @@ private string GetResourceName(PropertyInfo property, Type resourceType)
                 return resourceAttribute.ResourceName;
 
             // fallback to dsherized...this should actually check for a custom IResourceNameFormatter
-            return property.Name.Dasherize();            
+            return _resourceNameFormatter.FormatResourceName(resourceType);
         }
 
         private (bool isJsonApiResource, Type idType) GetIdType(Type resourceType)
@@ -213,5 +225,12 @@ private void AssertEntityIsNotAlreadyDefined(Type entityType)
             if (_entities.Any(e => e.EntityType == entityType))
                 throw new InvalidOperationException($"Cannot add entity type {entityType} to context graph, there is already an entity of that type configured.");
         }
+
+        /// <inheritdoc />
+        public IContextGraphBuilder UseNameFormatter(IResourceNameFormatter resourceNameFormatter)
+        {
+            _resourceNameFormatter = resourceNameFormatter;
+            return this;
+        }
     }
 }

src/JsonApiDotNetCore/Graph/TypeLocator.cs

@@ -6,11 +6,19 @@
 
 namespace JsonApiDotNetCore.Graph
 {
+    /// <summary>
+    /// Used to locate types and facilitate auto-resource discovery
+    /// </summary>
     internal static class TypeLocator
     {
         private static Dictionary<Assembly, Type[]> _typeCache = new Dictionary<Assembly, Type[]>();
         private static Dictionary<Assembly, List<ResourceDescriptor>> _identifiableTypeCache = new Dictionary<Assembly, List<ResourceDescriptor>>();
+
 
+        /// <summary>
+        /// Determine whether or not this is a json:api resource by checking if it implements <see cref="IIdentifiable"/>.
+        /// Returns the status and the resultant id type, either `(true, Type)` OR `(false, null)`
+        /// </summary>        
         public static (bool isJsonApiResource, Type idType) GetIdType(Type resourceType)
         {
             var identitifableType = GetIdentifiableIdType(resourceType);
@@ -37,6 +45,10 @@ private static Type[] GetAssemblyTypes(Assembly assembly)
             return types;
         }
 
+
+        /// <summary>
+        /// Get all implementations of <see cref="IIdentifiable"/>. in the assembly
+        /// </summary>
         public static List<ResourceDescriptor> GetIdentifableTypes(Assembly assembly)
         {
             if (_identifiableTypeCache.TryGetValue(assembly, out var descriptors) == false)
@@ -55,6 +67,17 @@ public static List<ResourceDescriptor> GetIdentifableTypes(Assembly assembly)
             return descriptors;
         }
 
+        /// <summary>
+        /// Get all implementations of the generic interface
+        /// </summary>
+        /// <param name="assembly">The assembly to search</param>
+        /// <param name="openGenericInterfaceType">The open generic type, e.g. `typeof(IResourceService&lt;&gt;)`</param>
+        /// <param name="genericInterfaceArguments">Parameters to the generic type</param>
+        /// <example>
+        /// <code>
+        /// GetGenericInterfaceImplementation(assembly, typeof(IResourceService&lt;&gt;), typeof(Article), typeof(Guid));
+        /// </code>
+        /// </example>
         public static (Type implementation, Type registrationInterface) GetGenericInterfaceImplementation(Assembly assembly, Type openGenericInterfaceType, params Type[] genericInterfaceArguments)
         {
             foreach (var type in assembly.GetTypes())
@@ -71,16 +94,33 @@ public static (Type implementation, Type registrationInterface) GetGenericInterf
             return (null, null);
         }
 
-        public static IEnumerable<Type> GetDerivedGenericTypes(Assembly assembly, Type openGenericType, Type genericArgument)
+        /// <summary>
+        /// Get all derivitives of the concrete, generic type.
+        /// </summary>
+        /// <param name="assembly">The assembly to search</param>
+        /// <param name="openGenericType">The open generic type, e.g. `typeof(ResourceDefinition&lt;&gt;)`</param>
+        /// <param name="genericArguments">Parameters to the generic type</param>
+        /// <example>
+        /// <code>
+        /// GetDerivedGenericTypes(assembly, typeof(ResourceDefinition<>), typeof(Article))
+        /// </code>
+        /// </example>
+        public static IEnumerable<Type> GetDerivedGenericTypes(Assembly assembly, Type openGenericType, params Type[] genericArguments)
         {
-            var genericType = openGenericType.MakeGenericType(genericArgument);
-            foreach (var type in assembly.GetTypes())
-            {
-                if (genericType.IsAssignableFrom(type))
-                    yield return type;
-            }
+            var genericType = openGenericType.MakeGenericType(genericArguments);
+            return GetDerivedTypes(assembly, genericType);
         }
 
+        /// <summary>
+        /// Get all derivitives of the specified type.
+        /// </summary>
+        /// <param name="assembly">The assembly to search</param>
+        /// <param name="openGenericType">The inherited type</param>
+        /// <example>
+        /// <code>
+        /// GetDerivedGenericTypes(assembly, typeof(DbContext))
+        /// </code>
+        /// </example>
         public static IEnumerable<Type> GetDerivedTypes(Assembly assembly, Type inheritedType)
         {
             foreach (var type in assembly.GetTypes())

src/JsonApiDotNetCore/JsonApiDotNetCore.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <VersionPrefix>2.5.1</VersionPrefix>
+    <VersionPrefix>3.0.0</VersionPrefix>
     <TargetFrameworks>$(NetStandardVersion)</TargetFrameworks>
     <AssemblyName>JsonApiDotNetCore</AssemblyName>
     <PackageId>JsonApiDotNetCore</PackageId>