OpenAPI: Hide inaccessible links

[bkoelman]

This PR updates OpenAPI to take into account whether JSON:API links are available.

My first take on implementing this was to declare nearly all links as required in the component schemas. Then at runtime remove the links we know can't be returned, which can be determined from the cascading links configuration.

However, because links can be configured per resource type, this requires expansion of the link schema types. For example, linksInResourceData becomes linksInTodoItemData, linksInPersonData, linksInTagData, etc. This introduces many new schemas for questionable gain, as using OpenAPI typically makes users care less about links. But it gets worse. Relationship links can be overruled per relationship within a resource type. This means we need to expand link schema types for them as well. But the relationship links are defined on the relationship left-type, whereas the currently produced schemas for relationships reflect their right-type. For example, todoItems contains relationships owner and assignee, both of type people. Let's assume both relationships are required. In that case, a single schema toOnePersonInResponse is produced for both relationships' right-side types, because they have the same data structure. Now taking expansion for relationship links into account, we'd need to generate separate schemas: ownerToOnePersonInResponse and assigneeToOnePersonInResponse. As a result, consumers can't write the following code anymore, because different schemas would be produced:

var todoItemsResponse = await _apiClient.GetTodoItemCollectionAsync(null, null);
var firstTodoItem = todoItemsResponse.Result.Data.First();

PrintPersonRelationship(firstTodoItem.Relationships.Owner);
PrintPersonRelationship(firstTodoItem.Relationships.Assignee);

private void PrintPersonRelationship(ToOnePersonInResponse person)
{
    // ....
}

For the reasons mentioned above, I chose not to implement schema expansion at all. The next best thing is to determine which links can be eliminated by taking a union of the configured link types. So if all links are turned off, but todoItems turns on the top-level self link, then all resource types get only the top-level self link. Likewise, if the owner relationship turns on the related relationship-level link, while the assignee relationship turns on the self link, then all relationship schemas get both links. If no link overrules are used and links are turned off in options, then no links appear in the component schemas.

As a result, all links must be declared as non-required in the component schemas, because now the schemas may contain links that won't actually be returned at runtime (and we haven't eliminated them from the schema).

Closes #1062.

QUALITY CHECKLIST

• Changes implemented in code
• Complies with our contributing guidelines
• Adapted tests
• N/A: Documentation updated

[codecov]

Codecov Report

Attention: Patch coverage is 97.77778% with 3 lines in your changes are missing coverage. Please review.

Project coverage is 90.85%. Comparing base (66be210) to head (7722b87).

Files	Patch %	Lines
...waggerComponents/LinksVisibilitySchemaGenerator.cs	96.87%	0 Missing and 3 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           openapi    #1518      +/-   ##
===========================================
+ Coverage    90.77%   90.85%   +0.07%     
===========================================
  Files          394      396       +2     
  Lines        12993    13115     +122     
  Branches      2058     2078      +20     
===========================================
+ Hits         11795    11916     +121     
+ Misses         782      781       -1     
- Partials       416      418       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[xontab]

@bkoelman Will this feature be released soon?

[bkoelman]

This is available for use from the GitHub NuGet feed, see https://github.com/json-api-dotnet/JsonApiDotNetCore/blob/master/README.md#trying-out-the-latest-build. The overall progress of adding OpenAPI support is tracked at #1046. It'll take a while to complete that, after which it'll be published to NuGet. To speed that up, you can help if you want by working on open issues.