Why Did We...

This aims to explain the decisions we've made with coding this backend. It's a loose bag o' things.

Mutable Record Classes for Requests 'n' ViewModels

TL;DR: it's the only way we can write in-depth documentation for them.

We want in-depth documentation for our code. By this, we mean being able to give descriptions and example values on individual fields.

We first tried writing readonly record structs with block-scoped fields. However, documentation wasn't being generated in the OpenAPI page. RageCage discovered that because the fields are non-settable, the reflection used by Swashbuckle can't do its job.

The alternative was to write positional arguments. The problem with that though is that you can't provide example values that way. Here's an example record class with positional arguments and doc comments:

/// <summary>Example positional record.</summary>
/// <param name="First">First argument</param>
public record ExamplePositional(string First) {}

The thing that sucks is that <param> only has the single name param. Nothing else. So no go there.

Using NodaTime

I originally wanted to stick with .NET's builtin DateTime type. But NPGSQL for .NET 6 doesn't like that. Found this out when running tests for Bans and I got this similar error. And the solution provided in that SO post really didn't sit well with me. Hence, NodaTime. That fixes datetime DB operations while not resorting to forcing legacy behaviour.