Improved JsonApiClient and relationships into openapi-required-and-nullable

[maurei]

This PR brings merges into #1185:

• For resource attributes: JsonApiClient improvements when dealing with nullable/required/default-value properties when NRT is on/off. Also contains extensive test coverage.
• For resource relationships: adjustment in JsonApiDotNetCore.OpenApi and extensive test coverage

For server-side testing (i.e. the generated OAS file), the table in #1111 provides a transparent overview for resource attributes of what is expected for required/nullable when NRT and/or MSV are on/off. This piece is already covered by #1185.

However, for client-side testing, that table doesn't clearly show which JsonApiClient behaviour during request is expected to fail and succeed. For that I've extended the overview in this PR to include relevant operations for which the client-side behaviour should be captured, see below. The overview is also extended to contain the same for relationships.

For instance, from this overview it reads:

A client should be able to generate a request intentionally in which the json property

• data.attributes.name is set to null (G9);
• data.attributes.name is omitted from the request body (G9);
• data.attributes.weight is set to its default value 0 (G12)

and should not be able to generate a request intentionally where

• data.attributes.weight is omitted from the request body (H12)

where these paths correspond to the Name/Weight properties on the Chicken resource as declared server-side, for the scenario: NRT disabled and MSV enabled

Few more details:

• Note that "NRT disabled" means: disabled both server-side and client-side. Therefore, the test cases in the PR are: 1 (server-on, client-on) and 2 (server-off, client-off). That implies we could for completeness also look into (server-on, client-off) and (server-off, client-on), but these scenarios don't generate any unique test cases. So I decided to leave it out for conciseness.
• the scenario (NRT off, MSV on) is included but not (NRT off, MSV off), because it is identical. To see this, compare columns FGH with KLM
• the scenario (NRT on, MSV on) is included but not (NRT on, MSV off), because it is nearly identical. Only I3 differs from C3, but that case doesn't deserve a new test suite because there are plenty of other cases already where omitting is not allowed in a similar circumstance.

[codecov]

Codecov Report

Merging #1231 (affc187) into openapi-required-and-nullable-properties (f5bb7fc) will increase coverage by 0.00%.
The diff coverage is 94.84%.

@@                            Coverage Diff                            @@
##           openapi-required-and-nullable-properties    #1231   +/-   ##
=========================================================================
  Coverage                                     92.38%   92.39%           
=========================================================================
  Files                                           303      304    +1     
  Lines                                          8855     8910   +55     
=========================================================================
+ Hits                                           8181     8232   +51     
- Misses                                          674      678    +4     

Impacted Files	Coverage Δ
...NetCore.OpenApi.Client/UnreachableCodeException.cs	0.00% <0.00%> (ø)
.../JsonApiDotNetCore.OpenApi.Client/JsonApiClient.cs	96.00% <96.59%> (ø)
...ggerComponents/ResourceFieldObjectSchemaBuilder.cs	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[maurei]

@bkoelman your two cents on the following please.

Compare the current RequestTests#Can_exclude_optional_relationships with the newly proposed AlternativeFormRequestTests#Can_exclude_optional_relationship.

In the first form (current form), it isn't clear by reading the test how many or which relationships are being omitted. Also it isn't clear that every omitted relationship represents a distinct and unrelated test case. So I realised that this test too should actually be a Theory. In the second format it is now immediately clear that OldestChicken and AllChickens are the relevant omitted properties and that they represent individual test cases.

It comes at the cost that the json assertion string is not as readable anymore. But given that before it didn't illuminate what was relevant either, even when it was readable, I argue that this isn't a problem. And when the test fails, it will still be readable in the log anyway.

Same would apply to the following remaining tests:

Can_exclude_optional_attributes
Can_exclude_attributes_that_are_required_for_POST_when_performing_PATCH
Can_clear_nullable_attributes
Can_set_default_value_to_ValueType_attributes
Can_exclude_relationships_that_are_required_for_POST_when_performing_PATCH

These tests only have one omitted property so technically don't need a theory, but could stil consider doing so to highlight which property is omitted:
Cannot_clear_required_attribute_when_performing_POST
Can_clear_nullable_relationship