Updated documentation

Author: Bart Koelman

README.md

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

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

@@ -7,7 +7,6 @@ The shortest path to a running API looks like:
 - Install
 - Define models
 - Define the DbContext
-- Define controllers
 - Add Middleware and Services
 - Seed the database
 - Start the app
@@ -40,6 +39,7 @@ The easiest way to do this is to inherit from `Identifiable<TId>`.
 ```c#
 #nullable enable
 
+[Resource]
 public class Person : Identifiable<int>
 {
     [Attr]
@@ -63,22 +63,6 @@ public class AppDbContext : DbContext
 }
 ```
 
-### Define Controllers
-
-You need to create controllers that inherit from `JsonApiController<TResource, TId>`
-where `TResource` is the model that inherits from `Identifiable<TId>`.
-
-```c#
-public class PeopleController : JsonApiController<Person, int>
-{
-    public PeopleController(IJsonApiOptions options, IResourceGraph resourceGraph,
-        ILoggerFactory loggerFactory, IResourceService<Person, int> resourceService)
-        : base(options, resourceGraph, loggerFactory, resourceService)
-    {
-    }
-}
-```
-
 ### Middleware and Services
 
 Finally, add the services by adding the following to your Startup.ConfigureServices:

docs/usage/extensibility/controllers.md

@@ -1,6 +1,99 @@
 # Controllers
 
-You need to create controllers that inherit from `JsonApiController<TResource, TId>`
+To expose API endpoints, ASP.NET controllers need to be defined.
+
+_since v5_
+
+Controllers are auto-generated (using [source generators](https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview)) when you add `[Resource]` on your model class:
+
+```c#
+[Resource] // Generates ArticlesController.g.cs
+public class Article : Identifiable<Guid>
+{
+    // ...
+}
+```
+
+## Resource Access Control
+
+It is often desirable to limit which endpoints are exposed on your controller.
+A subset can be specified too:
+
+```c#
+[Resource(GenerateControllerEndpoints =
+    JsonApiEndpoints.GetCollection | JsonApiEndpoints.GetSingle)]
+public class Article : Identifiable<Guid>
+{
+    // ...
+}
+```
+
+Instead of passing a set of endpoints, you can use `JsonApiEndpoints.Query` to generate all read-only endpoints or `JsonApiEndpoints.Command` for all write-only endpoints.
+
+When an endpoint is blocked, an HTTP 403 Forbidden response is returned.
+
+```http
+DELETE http://localhost:14140/articles/1 HTTP/1.1
+```
+
+```json
+{
+  "links": {
+    "self": "/articles"
+  },
+  "errors": [
+    {
+      "id": "dde7f219-2274-4473-97ef-baac3e7c1487",
+      "status": "403",
+      "title": "The requested endpoint is not accessible.",
+      "detail": "Endpoint '/articles/1' is not accessible for DELETE requests."
+    }
+  ]
+}
+```
+
+## Augmenting controllers
+
+Auto-generated controllers can easily be augmented because they are partial classes. For example:
+
+```c#
+[DisableRoutingConvention]
+[Route("some/custom/route")]
+[DisableQueryString(JsonApiQueryStringParameters.Include)]
+partial class ArticlesController
+{
+    [HttpPost]
+    public IActionResult Upload()
+    {
+        // ...
+    }
+}
+```
+
+If you need to inject extra dependencies, tell the IoC container with `[ActivatorUtilitiesConstructor]` to prefer your constructor:
+
+```c#
+partial class ArticlesController
+{
+    private IAuthenticationService _authService;
+
+    [ActivatorUtilitiesConstructor]
+    public ArticlesController(IAuthenticationService authService, IJsonApiOptions options,
+        IResourceGraph resourceGraph, ILoggerFactory loggerFactory,
+        IResourceService<Article, Guid> resourceService)
+            : base(options, resourceGraph, loggerFactory, resourceService)
+    {
+        _authService = authService;
+    }
+}
+```
+
+In case you don't want to use auto-generated controllers and define them yourself (see below), remove
+`[Resource]` from your models or use `[Resource(GenerateControllerEndpoints = JsonApiEndpoints.None)]`.
+
+## Earlier versions
+
+In earlier versions of JsonApiDotNetCore, you needed to create controllers that inherit from `JsonApiController<TResource, TId>`. For example:
 
 ```c#
 public class ArticlesController : JsonApiController<Article, Guid>
@@ -15,7 +108,7 @@ public class ArticlesController : JsonApiController<Article, Guid>
 
 If you want to setup routes yourself, you can instead inherit from `BaseJsonApiController<TResource, TId>` and override its methods with your own `[HttpGet]`, `[HttpHead]`, `[HttpPost]`, `[HttpPatch]` and `[HttpDelete]` attributes added on them. Don't forget to add `[FromBody]` on parameters where needed.
 
-## Resource Access Control
+### Resource Access Control
 
 It is often desirable to limit which routes are exposed on your controller.
 
@@ -37,25 +130,3 @@ public class ReportsController : JsonApiController<Report, int>
 ```
 
 For more information about resource service injection, see [Replacing injected services](~/usage/extensibility/layer-overview.md#replacing-injected-services) and [Resource Services](~/usage/extensibility/services.md).
-
-When a route is blocked, an HTTP 403 Forbidden response is returned.
-
-```http
-DELETE http://localhost:14140/people/1 HTTP/1.1
-```
-
-```json
-{
-  "links": {
-    "self": "/api/v1/people"
-  },
-  "errors": [
-    {
-      "id": "dde7f219-2274-4473-97ef-baac3e7c1487",
-      "status": "403",
-      "title": "The requested endpoint is not accessible.",
-      "detail": "Endpoint '/people/1' is not accessible for DELETE requests."
-    }
-  ]
-}
-```

docs/usage/extensibility/services.md

@@ -1,7 +1,8 @@
 # Resource Services
 
 The `IResourceService` acts as a service layer between the controller and the data access layer.
-This allows you to customize it however you want. This is also a good place to implement custom business logic.
+This allows you to customize it however you want. While this is still a potential place to implement custom business logic,
+since v4, [Resource Definitions](~/usage/extensibility/resource-definitions.md) are more suitable for that.
 
 ## Supplementing Default Behavior
 
@@ -77,7 +78,7 @@ public class ProductService : IResourceService<Product, int>
 
 ## Limited Requirements
 
-In some cases it may be necessary to only expose a few methods on a resource. For this reason, we have created a hierarchy of service interfaces that can be used to get the exact implementation you require.
+In some cases it may be necessary to only expose a few actions on a resource. For this reason, we have created a hierarchy of service interfaces that can be used to get the exact implementation you require.
 
 This interface hierarchy is defined by this tree structure.
 
@@ -152,7 +153,18 @@ public class Startup
 }
 ```
 
-Then in the controller, you should inherit from the JSON:API controller and pass the services into the named, optional base parameters:
+Then on your model, pass in the set of endpoints to expose (the ones that you've registered services for):
+
+```c#
+[Resource(GenerateControllerEndpoints =
+    JsonApiEndpoints.Create | JsonApiEndpoints.Delete)]
+public class Article : Identifiable<int>
+{
+    // ...
+}
+```
+
+Alternatively, when using a hand-written controller, you should inherit from the JSON:API controller and pass the services into the named, optional base parameters:
 
 ```c#
 public class ArticlesController : JsonApiController<Article, int>

docs/usage/resource-graph.md

@@ -72,28 +72,28 @@ public void ConfigureServices(IServiceCollection services)
 
 ## Resource Name
 
-The public resource name is exposed through the `type` member in the JSON:API payload. This can be configured by the following approaches (in order of priority):
+The public resource name is exposed through the `type` member in the JSON:API payload. This can be configured using the following approaches (in order of priority):
 
-1. The `publicName` parameter when manually adding a resource to the graph
+1. The `publicName` parameter when manually adding a resource to the graph.
 ```c#
 services.AddJsonApi(resources: builder =>
 {
-    builder.Add<Person, int>(publicName: "people");
+    builder.Add<Person, int>(publicName: "individuals");
 });
 ```
 
-2. The model is decorated with a `ResourceAttribute`
+2. The `PublicName` property when a model is decorated with a `ResourceAttribute`.
 ```c#
-[Resource("myResources")]
-public class MyModel : Identifiable<int>
+[Resource(PublicName = "individuals")]
+public class Person : Identifiable<int>
 {
 }
 ```
 
-3. The configured naming convention (by default this is camel-case).
+3. The configured naming convention (by default this is camel-case), after pluralization.
 ```c#
-// this will be registered as "myModels"
-public class MyModel : Identifiable<int>
+// this will be registered as "people"
+public class Person : Identifiable<int>
 {
 }
 ```

docs/usage/routing.md

@@ -6,7 +6,7 @@ An endpoint URL provides access to a resource or a relationship. Resource endpoi
 
 In the relationship endpoint "/articles/1/relationships/comments", "articles" is the left side of the relationship and "comments" the right side.
 
-## Namespacing and Versioning URLs
+## Namespacing and versioning of URLs
 You can add a namespace to all URLs by specifying it in ConfigureServices.
 
 ```c#
@@ -18,15 +18,18 @@ public void ConfigureServices(IServiceCollection services)
 
 Which results in URLs like: https://yourdomain.com/api/v1/people
 
-## Default Routing Convention
+## Default routing convention
 
-The library will configure routes for all controllers in your project. By default, routes are camel-cased. This is based on the [recommendations](https://jsonapi.org/recommendations/) outlined in the JSON:API spec.
+The library will configure routes for all auto-generated and hand-written controllers in your project. By default, routes are camel-cased. This is based on the [recommendations](https://jsonapi.org/recommendations/) outlined in the JSON:API spec.
 
 ```c#
-public class OrderLine : Identifiable<int>
+// Auto-generated
+[Resource]
+public class OrderSummary : Identifiable<int>
 {
 }
 
+// Hand-written
 public class OrderLineController : JsonApiController<OrderLine, int>
 {
     public OrderLineController(IJsonApiOptions options, IResourceGraph resourceGraph,
@@ -38,6 +41,7 @@ public class OrderLineController : JsonApiController<OrderLine, int>
 ```
 
 ```http
+GET /orderSummaries HTTP/1.1
 GET /orderLines HTTP/1.1
 ```
 
@@ -57,12 +61,21 @@ public class OrderLineController : ControllerBase
 GET /orderLines HTTP/1.1
 ```
 
-## Disabling the Default Routing Convention
+### Customized routes
 
-It is possible to bypass the default routing convention for a controller.
+It is possible to override the default routing convention for an auto-generated or hand-written controller.
 
 ```c#
-[Route("v1/custom/route/lines-in-order"), DisableRoutingConvention]
+// Auto-generated
+[DisableRoutingConvention]
+[Route("v1/custom/route/summaries-for-orders")]
+partial class OrderSummariesController
+{
+}
+
+// Hand-written
+[DisableRoutingConvention]
+[Route("v1/custom/route/lines-in-order")]
 public class OrderLineController : JsonApiController<OrderLine, int>
 {
     public OrderLineController(IJsonApiOptions options, IResourceGraph resourceGraph,
@@ -73,7 +86,7 @@ public class OrderLineController : JsonApiController<OrderLine, int>
 }
 ```
 
-## Advanced Usage: Custom Routing Convention
+## 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`.