OpenAPI: Auto-generated documentation (#1371)

* Generate documentation for JSON:API endpoints

* Generate documentation for JSON:API resource types and attributes

* Rename path property, which is actually a directory

* Add 403 status when client-generated IDs are forbidden (default)

* Update documentation

docs/usage/openapi.md

@@ -1,6 +1,8 @@
 # OpenAPI
 
-JsonApiDotNetCore provides an extension package that enables you to produce an [OpenAPI specification](https://swagger.io/specification/) for your JSON:API endpoints. This can be used to generate a [documentation website](https://swagger.io/tools/swagger-ui/) or to generate [client libraries](https://openapi-generator.tech/docs/generators/) in various languages. The package provides an integration with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).
+JsonApiDotNetCore provides an extension package that enables you to produce an [OpenAPI specification](https://swagger.io/specification/) for your JSON:API endpoints.
+This can be used to generate a [documentation website](https://swagger.io/tools/swagger-ui/) or to generate [client libraries](https://openapi-generator.tech/docs/generators/) in various languages.
+The package provides an integration with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).
 
 
 ## Getting started
@@ -35,10 +37,29 @@ By default, the OpenAPI specification will be available at `http://localhost:<po
 
 ## Documentation
 
-Swashbuckle also ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), which enables to visualize and interact with the API endpoints through a web page. This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Program.cs` file:
+### SwaggerUI
+
+Swashbuckle also ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), which enables to visualize and interact with the API endpoints through a web page.
+This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Program.cs` file:
 
 ```c#
 app.UseSwaggerUI();
 ```
 
 By default, SwaggerUI will be available at `http://localhost:<port>/swagger`.
+
+### Triple-slash comments
+
+Documentation for JSON:API endpoints is provided out of the box, which shows in SwaggerUI and through IDE IntelliSense in auto-generated clients.
+To also get documentation for your resource classes and their properties, add the following to your project file.
+The `NoWarn` line is optional, which suppresses build warnings for undocumented types and members.
+
+```xml
+  <PropertyGroup>
+    <GenerateDocumentationFile>True</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);1591</NoWarn>
+  </PropertyGroup>
+```
+
+You can combine this with the documentation that Swagger itself supports, by enabling it as described [here](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments).
+This adds documentation for additional types, such as triple-slash comments on enums used in your resource models.

src/JsonApiDotNetCore.OpenApi/JsonApiOperationIdSelector.cs

@@ -116,7 +116,7 @@ private string ApplyTemplate(string operationIdTemplate, ResourceType resourceTy
         string relationshipName = operationIdTemplate.Contains("[RelationshipName]") ? endpoint.RelativePath.Split("/").Last() : string.Empty;
 
         // @formatter:wrap_chained_method_calls chop_always
-        // @formatter:wrap_before_first_method_call true true
+        // @formatter:wrap_before_first_method_call true
 
         string pascalCaseOperationId = operationIdTemplate
             .Replace("[Method]", method)

src/JsonApiDotNetCore.OpenApi/ServiceCollectionExtensions.cs

@@ -70,6 +70,7 @@ private static void AddSwaggerGenerator(IServiceScope scope, IServiceCollection
             SetOperationInfo(swaggerGenOptions, controllerResourceMapping, namingPolicy);
             SetSchemaIdSelector(swaggerGenOptions, resourceGraph, namingPolicy);
             swaggerGenOptions.DocumentFilter<EndpointOrderingFilter>();
+            swaggerGenOptions.OperationFilter<JsonApiOperationDocumentationFilter>();
 
             setupSwaggerGenAction?.Invoke(swaggerGenOptions);
         });

src/JsonApiDotNetCore.OpenApi/SwaggerComponents/EndpointOrderingFilter.cs

@@ -16,12 +16,12 @@ public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
         ArgumentGuard.NotNull(swaggerDoc);
         ArgumentGuard.NotNull(context);
 
-        List<KeyValuePair<string, OpenApiPathItem>> orderedEndpoints = swaggerDoc.Paths.OrderBy(GetPrimaryResourcePublicName)
+        List<KeyValuePair<string, OpenApiPathItem>> endpointsInOrder = swaggerDoc.Paths.OrderBy(GetPrimaryResourcePublicName)
             .ThenBy(GetRelationshipName).ThenBy(IsSecondaryEndpoint).ToList();
 
         swaggerDoc.Paths.Clear();
 
-        foreach ((string url, OpenApiPathItem path) in orderedEndpoints)
+        foreach ((string url, OpenApiPathItem path) in endpointsInOrder)
         {
             swaggerDoc.Paths.Add(url, path);
         }