OpenAPI: Auto-generated documentation

[bkoelman]

This PR adds auto-generated documentation for JSON:API endpoints, resource types, and attributes to the OAS file. Comments on relationships are currently ignored, due to a limitation in OAS 3.0. This can likely be worked around by using allOf operators. The same limitation applies to attributes of enum types. Resolved by #1372.

The comments on endpoints (expanded controller action methods) are hardcoded. Triple-slash comments on resource classes and their properties are extracted by loading the .xml file next to their assembly. Add <GenerateDocumentationFile>true</GenerateDocumentationFile> to your project file to make this work. To get additional documentation, such as triple-slash comments on enum types, call SwaggerGenOptions.IncludeXmlComments() as described here.

Adding partial controllers to your project and decorating the action methods with custom triple-slash comments is possible. They will override the hardcoded descriptions, but to a certain degree. It won't work for endpoints that take a relationship name, due to relationship expansion at runtime.

Additionally, this PR adds in all the applicable HTTP status codes that JsonApiDotNetCore returns per endpoint. And it fixes the bug where response bodies are shown for HEAD requests.

Demo

Screenshots below for an API comprising of skyscrapers, spaces, and elevators.

Endpoints

Parameters and response codes

Triple-slash comments from resource type and attributes

/// <summary>
/// A tall, continuously habitable building having multiple floors.
/// </summary>
[UsedImplicitly(ImplicitUseTargetFlags.Members)]
[Resource]
public sealed class Skyscraper : Identifiable<long>
{
    /// <summary>
    /// The height of this building, in meters.
    /// </summary>
    [Attr]
    [Required]
    public int? HeightInMeters { get; set; }

    /// <summary>
    /// An optional elevator within this building, providing access to spaces.
    /// </summary>
    [HasOne]
    public Elevator? Elevator { get; set; }

    /// <summary>
    /// The spaces within this building.
    /// </summary>
    [HasMany]
    public ISet<Space> Spaces { get; set; } = new HashSet<Space>();
}

IntelliSense on generated C# client

Closes #1053.
Fixes #1369.
Fixes #1368.

QUALITY CHECKLIST

• Changes implemented in code
• Complies with our contributing guidelines
• Adapted tests
• NA: Documentation updated

[codecov]

Codecov Report

Merging #1371 (c058c80) into openapi (86af528) will increase coverage by 0.17%.
The diff coverage is 94.11%.

@@             Coverage Diff             @@
##           openapi    #1371      +/-   ##
===========================================
+ Coverage    90.07%   90.25%   +0.17%     
===========================================
  Files          306      308       +2     
  Lines         9904    10137     +233     
  Branches      1661     1691      +30     
===========================================
+ Hits          8921     9149     +228     
- Misses         651      653       +2     
- Partials       332      335       +3     

Files	Coverage Δ
...piDotNetCore.OpenApi/JsonApiOperationIdSelector.cs	84.90% <ø> (ø)
...iDotNetCore.OpenApi/ServiceCollectionExtensions.cs	95.71% <100.00%> (+0.06%)	⬆️
...penApi/SwaggerComponents/EndpointOrderingFilter.cs	100.00% <100.00%> (ø)
...ggerComponents/ResourceFieldObjectSchemaBuilder.cs	99.06% <100.00%> (+0.02%)	⬆️
...SwaggerComponents/ResourceObjectSchemaGenerator.cs	100.00% <100.00%> (+6.25%)	⬆️
...rComponents/JsonApiOperationDocumentationFilter.cs	97.90% <97.90%> (ø)
...gerComponents/ResourceObjectDocumentationReader.cs	72.22% <72.22%> (ø)

... and 2 files with indirect coverage changes