Auto-generated JSON:API controllers using source generators

[bart-degreed]

Usage

To generate a controller, decorate your resource class with [Resource]. For example:

[Resource] // Generates ProductsController.g.cs
public class Product : Identifiable<long>
{
    // ...
}

This enables to choose per resource type if a controller should be generated or not.

A subset of exposed endpoints can be specified too:

[Resource(GenerateControllerEndpoints = JsonApiEndpoints.GetCollection | JsonApiEndpoints.GetSingle)]
public class Product : Identifiable<long>
{
    // ...
}

Auto-generated controllers can easily be augmented because they are partial classes. For example:

[DisableRoutingConvention]
[Route("some/custom/route")]
[DisableQueryString(JsonApiQueryStringParameters.Include)]
partial class ProductsController
{
    [HttpPost]
    public IActionResult Upload()
    {
        // ...
    }
}

In Visual Studio, Solution Explorer shows what code was generated:

Implementation

Alternatives

An alternative solution I considered is to dynamically register controllers to ASP.NET at runtime, basically #900.

Several reasons why I believe source generators are the better choice here:

• Debugging: developers can inspect what was generated, breakpoints can be added to step into auto-generated controllers.
• Flexibility in augmenting the generated controllers with attributes and custom code, they are partial classes.
• Reduced startup costs, no reflection, or facing cryptic runtime resolve errors.
• Provide feedback at compile time by emitting build warnings, for example: "resource does not implement IIdentifiable".
• Less code to implement in JADNC: many checks are caught by the compiler, such as missing references/usings, duplicate classes.
• Easy to unit test: does not require starting up a web server.

Notes:

• Fixed: Attributes DisableRoutingConvention, DisableQueryString, JsonPropertyName and Resource used on base classes did not work.
• Reduced dependency from Humanizer to Humanizer.Core, which only contains basic rules and the English language. I assumed that calls like Pluralize() would take language rules into account, but this is not the case. The localized satellite assemblies just contain texts such as "one week ago", "yesterday" etc, which we don't use.
• ResourceAttribute.PublicName is now optional. This means existing code [Resource("articles")] needs to be changed to: [Resource(PublicName: "articles")].
• Use [ActivatorUtilitiesConstructor] to force the IoC container to choose your own controller constructor with extra dependencies.
• Visual Studio is unable to unload/reload source generators. So if editing the source generator code and things don't work as expected, restart the IDE.
• Rider is unable to debug into source generators, except when debugging from a source-generator unit test.

Helpful links for future reference (when developing source generators):

• How to debug a source generator in Visual Studio: http://stevetalkscode.co.uk/debug-source-generators-with-vs2019-1610
• Debugging into a source generator from anything but a very simplistic demo project (like an ASP.NET API, a project with multiple NuGet dependencies, etc), does not work: https://developercommunity.visualstudio.com/t/unable-to-debug-source-generator-with-the-new-rosl/1398618
• Source generator pain points: https://turnerj.com/blog/the-pain-points-of-csharp-source-generators
• Consuming NuGet packages in a source generator can be a nightmare because it does not support transitive dependencies: Support automatic transient dependency packaging for source generators dotnet/sdk#17775
• Source generators cookbook: https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.cookbook.md
• Other useful links: https://gist.github.com/TessenR/ab40df2d6e971a8d6e5c6c6295d85d11

Closes #732
Closes #365

QUALITY CHECKLIST

• Changes implemented in code
• Complies with our contributing guidelines
• Adapted tests
• Documentation updated
• N/A: Created issue to update Templates: {ISSUE_NUMBER}

[codecov]

Codecov Report

Merging #1117 (b545d90) into master (e65b65a) will increase coverage by 0.40%.
The diff coverage is 97.59%.

@@            Coverage Diff             @@
##           master    #1117      +/-   ##
==========================================
+ Coverage   89.00%   89.41%   +0.40%     
==========================================
  Files         249      245       -4     
  Lines        7123     7294     +171     
==========================================
+ Hits         6340     6522     +182     
+ Misses        783      772      -11     

Impacted Files	Coverage Δ
...Examples/JsonApiDotNetCoreExample/Models/Person.cs	0.00% <ø> (ø)
...rc/Examples/JsonApiDotNetCoreExample/Models/Tag.cs	0.00% <ø> (ø)
...amples/JsonApiDotNetCoreExample/Models/TodoItem.cs	0.00% <ø> (ø)
...Examples/MultiDbContextExample/Models/ResourceA.cs	100.00% <ø> (ø)
...Examples/MultiDbContextExample/Models/ResourceB.cs	100.00% <ø> (ø)
...amples/NoEntityFrameworkExample/Models/WorkItem.cs	100.00% <ø> (ø)
...rollers/Annotations/DisableQueryStringAttribute.cs	100.00% <ø> (ø)
...re/Resources/Annotations/ResourceLinksAttribute.cs	100.00% <ø> (ø)
...iDotNetCore/Configuration/ResourceNameFormatter.cs	88.88% <66.66%> (+1.38%)	⬆️
...ApiDotNetCore.SourceGenerators/SourceCodeWriter.cs	97.58% <97.58%> (ø)
... and 9 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e65b65a...b545d90. Read the comment docs.