Add Description for HotChocolate Usage in Data Gateway

[seantleonard]

Can anyone provide insight about the way we are using HotChocolate? I see in this PR, Jelte mentions we are using HotChocolate in an uncommon way resulting in us not being able to really rely on HotChocolate Docs and examples. Is there something about our DataGateway design that requires this?

For example, in the startup.cs class, we could be using something like Interceptors | ChilliCream GraphQL Platform shows:

services
    .AddGraphQLServer()
    .AddHttpRequestInterceptor<HttpRequestInterceptor>();

We instead defer all HotChocolate setup to the GraphQLService class here to manually setup the ISchema, IRequestExecutorBuilder, and IRequestExecutor. Perhaps this usage is more relevant to older HotChocolate versions(v10, v11) as we are using v12. The service setup above .AddGraphQLServer() does the work that we have manually pulled out.

One limitation that I have encountered so far, or at least have not been able to solve, is how to properly had the HotChocolate Default HTTP Request interceptor. This would allow me to not have to manually populate the ClaimsPrincipal object in my Authentication PR. (#97)

It would be beneficial to have context to our HotChocolate usage in our repo. After having read through relevant sections of HotChocolate source, there are class files that can be referenced to help existing and new contributors identify how to build out GraphQL features in DataGateway.

[aaronpowell]

I'd also like to understand a bit more about why we have a custom controller rather than using interceptors in HotChocolate.

I've fixed a few bugs (#290 and #315 for example) which are related to the custom parsing of the GraphQL request before handing back to HotChocolate.

Also, with our custom controller we're currently only supporting POST requests for GraphQL, when it's valid to use GET as the HTTP verb as well, something which HotChocolate can handle for us.

Lastly, we'd get batching support for queries and mutations, which will help tackle the scenarios recently discussed around transations, otherwise the controller is going to need to do a bit more decision work on whether it's a batch request or not.