Various corrections in documentation, added #nullable where it makes a difference

Author: Bart Koelman

README.md

@@ -43,21 +43,23 @@ See [our documentation](https://www.jsonapi.net/) for detailed usage.
 ### Models
 
 ```c#
-public class Article : Identifiable
+#nullable enable
+
+public class Article : Identifiable<int>
 {
     [Attr]
-    public string Name { get; set; }
+    public string Name { get; set; } = null!;
 }
 ```
 
 ### Controllers
 
 ```c#
-public class ArticlesController : JsonApiController<Article>
+public class ArticlesController : JsonApiController<Article, int>
 {
-    public ArticlesController(IJsonApiOptions options, ILoggerFactory loggerFactory,
-        IResourceService<Article> resourceService,)
-        : base(options, loggerFactory, resourceService)
+    public ArticlesController(IJsonApiOptions options, IResourceGraph resourceGraph,
+        ILoggerFactory loggerFactory, IResourceService<Article, int> resourceService)
+        : base(options, resourceGraph, loggerFactory, resourceService)
     {
     }
 }

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

@@ -38,10 +38,12 @@ Define your domain models such that they implement `IIdentifiable<TId>`.
 The easiest way to do this is to inherit from `Identifiable<TId>`.
 
 ```c#
+#nullable enable
+
 public class Person : Identifiable<int>
 {
     [Attr]
-    public string Name { get; set; }
+    public string Name { get; set; } = null!;
 }
 ```
 
@@ -52,12 +54,12 @@ Nothing special here, just an ordinary `DbContext`.
 ```
 public class AppDbContext : DbContext
 {
+    public DbSet<Person> People => Set<Person>();
+
     public AppDbContext(DbContextOptions<AppDbContext> options)
         : base(options)
     {
     }
-
-    public DbSet<Person> People { get; set; }
 }
 ```
 

docs/home/index.html

@@ -142,31 +142,35 @@ <h2>Example usage</h2>
                      <div class="icon"><i class='bx bx-detail'></i></div>
                      <h4 class="title">Resource</h4>
                      <pre>
-<code>public class Article : Identifiable
+<code>#nullable enable
+
+public class Article : Identifiable&lt;long&gt;
 {
     [Attr]
-    [Required, MaxLength(30)]
-    public string Title { get; set; }
+    [MaxLength(30)]
+    public string Title { get; set; } = null!;
 
     [Attr(Capabilities = AttrCapabilities.AllowFilter)]
-    public string Summary { get; set; }
+    public string? Summary { get; set; }
 
     [Attr(PublicName = "websiteUrl")]
-    public string Url { get; set; }
+    public string? Url { get; set; }
+
+    [Attr]
+    [Required]
+    public int? WordCount { get; set; }
 
     [Attr(Capabilities = AttrCapabilities.AllowView)]
     public DateTimeOffset LastModifiedAt { get; set; }
 
     [HasOne]
-    public Person Author { get; set; }
+    public Person Author { get; set; } = null!;
 
-    [HasMany]
-    public ICollection&lt;Revision&gt; Revisions { get; set; }  
+    [HasOne]
+    public Person? Reviewer { get; set; }
 
-    [HasManyThrough(nameof(ArticleTags))]
-    [NotMapped]
-    public ICollection&lt;Tag&gt; Tags { get; set; }
-    public ICollection&lt;ArticleTag&gt; ArticleTags { get; set; }
+    [HasMany]
+    public ICollection&lt;Tag&gt; Tags { get; set; } = new HashSet&lt;Tag&gt;();
 }</code>
                      </pre>
                   </div>
@@ -179,7 +183,7 @@ <h4 class="title">Resource</h4>
                      <h4 class="title">Request</h4>
                      <pre>
 <code>
-GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author HTTP/1.1
+GET /articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields[articles]=title,summary&include=author HTTP/1.1
 </code>
                      </pre>
                   </div>
@@ -197,9 +201,9 @@ <h4 class="title">Response</h4>
     "totalResources": 1
   },
   "links": {
-    "self": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author",
-    "first": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author",
-    "last": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields=title,summary&include=author"
+    "self": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
+    "first": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author",
+    "last": "/articles?filter=contains(summary,'web')&sort=-lastModifiedAt&fields%5Barticles%5D=title,summary&include=author"
   },
   "data": [
     {

docs/usage/errors.md

@@ -10,7 +10,7 @@ From a controller method:
 return Conflict(new Error(HttpStatusCode.Conflict)
 {
     Title = "Target resource was modified by another user.",
-    Detail = $"User {userName} changed the {resourceField} field on the {resourceName} resource."
+    Detail = $"User {userName} changed the {resourceField} field on {resourceName} resource."
 });
 ```
 
@@ -20,7 +20,7 @@ From other code:
 throw new JsonApiException(new Error(HttpStatusCode.Conflict)
 {
     Title = "Target resource was modified by another user.",
-    Detail = $"User {userName} changed the {resourceField} field on the {resourceName} resource."
+    Detail = $"User {userName} changed the {resourceField} field on {resourceName} resource."
 });
 ```
 
@@ -69,18 +69,22 @@ public class CustomExceptionHandler : ExceptionHandler
         return base.GetLogMessage(exception);
     }
 
-    protected override ErrorDocument CreateErrorDocument(Exception exception)
+    protected override IReadOnlyList<ErrorObject> CreateErrorResponse(Exception exception)
     {
         if (exception is ProductOutOfStockException productOutOfStock)
         {
-            return new ErrorDocument(new Error(HttpStatusCode.Conflict)
+            return new[]
             {
-                Title = "Product is temporarily available.",
-                Detail = $"Product {productOutOfStock.ProductId} cannot be ordered at the moment."
-            });
+                new Error(HttpStatusCode.Conflict)
+                {
+                    Title = "Product is temporarily available.",
+                    Detail = $"Product {productOutOfStock.ProductId} " +
+                        "cannot be ordered at the moment."
+                }
+            };
         }
 
-        return base.CreateErrorDocument(exception);
+        return base.CreateErrorResponse(exception);
     }
 }
 

docs/usage/extensibility/services.md

@@ -19,7 +19,8 @@ public class TodoItemService : JsonApiResourceService<TodoItem, int>
         IQueryLayerComposer queryLayerComposer, IPaginationContext paginationContext,
         IJsonApiOptions options, ILoggerFactory loggerFactory, IJsonApiRequest request,
         IResourceChangeTracker<TodoItem> resourceChangeTracker,
-        IResourceDefinitionAccessor resourceDefinitionAccessor)
+        IResourceDefinitionAccessor resourceDefinitionAccessor,
+        INotificationService notificationService)
         : base(repositoryAccessor, queryLayerComposer, paginationContext, options,
             loggerFactory, request, resourceChangeTracker, resourceDefinitionAccessor)
     {
@@ -121,7 +122,7 @@ IResourceService
 In order to take advantage of these interfaces you first need to register the service for each implemented interface.
 
 ```c#
-public class ArticleService : ICreateService<Article>, IDeleteService<Article>
+public class ArticleService : ICreateService<Article, int>, IDeleteService<Article, int>
 {
     // ...
 }
@@ -130,8 +131,8 @@ public class Startup
 {
     public void ConfigureServices(IServiceCollection services)
     {
-        services.AddScoped<ICreateService<Article>, ArticleService>();
-        services.AddScoped<IDeleteService<Article>, ArticleService>();
+        services.AddScoped<ICreateService<Article, int>, ArticleService>();
+        services.AddScoped<IDeleteService<Article, int>, ArticleService>();
     }
 }
 ```

docs/usage/meta.md

@@ -8,14 +8,16 @@ Global metadata can be added to the root of the response document by registering
 This is useful if you need access to other registered services to build the meta object.
 
 ```c#
+#nullable enable
+
 // In Startup.ConfigureServices
 services.AddSingleton<IResponseMeta, CopyrightResponseMeta>();
 
 public sealed class CopyrightResponseMeta : IResponseMeta
 {
-    public IReadOnlyDictionary<string, object> GetMeta()
+    public IReadOnlyDictionary<string, object?> GetMeta()
     {
-        return new Dictionary<string, object>
+        return new Dictionary<string, object?>
         {
             ["copyright"] = "Copyright (C) 2002 Umbrella Corporation.",
             ["authors"] = new[] { "Alice", "Red Queen" }
@@ -42,21 +44,23 @@ public sealed class CopyrightResponseMeta : IResponseMeta
 Resource-specific metadata can be added by implementing `IResourceDefinition<TResource, TId>.GetMeta` (or overriding it on `JsonApiResourceDefinition<TResource, TId>`):
 
 ```c#
+#nullable enable
+
 public class PersonDefinition : JsonApiResourceDefinition<Person, int>
 {
     public PersonDefinition(IResourceGraph resourceGraph)
         : base(resourceGraph)
     {
     }
 
-    public override IReadOnlyDictionary<string, object> GetMeta(Person person)
+    public override IReadOnlyDictionary<string, object?>? GetMeta(Person person)
     {
         if (person.IsEmployee)
         {
-            return new Dictionary<string, object>
+            return new Dictionary<string, object?>
             {
                 ["notice"] = "Check our intranet at http://www.example.com/employees/" +
-                    person.StringId + " for personal details."
+                    $"{person.StringId} for personal details."
             };
         }
 

docs/usage/options.md

@@ -115,14 +115,19 @@ options.ValidateModelState = true;
 ```
 
 ```c#
+#nullable enable
+
 public class Person : Identifiable<int>
 {
     [Attr]
-    [Required]
     [MinLength(3)]
-    public string FirstName { get; set; }
+    public string FirstName { get; set; } = null!;
 
+    [Attr]
     [Required]
-    public LoginAccount Account : get; set; }
+    public int? Age { get; set; }
+
+    [HasOne]
+    public LoginAccount Account { get; set; } = null!;
 }
 ```

docs/usage/resource-graph.md

@@ -65,7 +65,7 @@ public void ConfigureServices(IServiceCollection services)
 {
     services.AddJsonApi(resources: builder =>
     {
-        builder.Add<Person>();
+        builder.Add<Person, int>();
     });
 }
 ```
@@ -78,7 +78,7 @@ The public resource name is exposed through the `type` member in the JSON:API pa
 ```c#
 services.AddJsonApi(resources: builder =>
 {
-    builder.Add<Person>(publicName: "people");
+    builder.Add<Person, int>(publicName: "people");
 });
 ```