Adjusted docs and minor refactors

Author: maurei

docs/usage/openapi/client-generator.md

@@ -0,0 +1,137 @@
+# Client Generator
+
+You can you can generate a client library from an OpenAPI specification that describes a JsonApiDotNetCore application. For clients genearted with using [NSwag](http://stevetalkscode.co.uk/openapireference-commands) we provide an additional package that enables partial write requests.
+
+## Installation
+
+You are required to install the following NuGet packages:
+
+- `JsonApiDotNetCore.OpenApiClient`
+- `NSwag.ApiDescription.Client`
+- `Microsoft.Extensions.ApiDescription.Cient`
+- `NSwag.ApiDescription.Client`
+
+The following examples demonstrate how to install the `JsonApiDotNetCore.OpenApiClient` package.
+
+### CLI
+
+```
+dotnet add package JsonApiDotNetCore.OpenApiClient
+```
+
+### Visual Studio
+
+```powershell
+Install-Package JsonApiDotNetCore.OpenApiClient
+```
+
+### *.csproj
+
+```xml
+<ItemGroup>
+  <!-- Be sure to check NuGet for the latest version # -->
+  <PackageReference Include="JsonApiDotNetCore.OpenApiClient" Version="4.0.0" />
+</ItemGroup>
+```
+
+
+## Adding an OpenApiReference
+
+Add a reference to your OpenAPI specification in your project file as demonstrated below.
+
+```xml
+<ItemGroup>
+ <OpenApiReference Include="swagger.json">
+   <Namespace>ApiConsumer.GeneratedCode</Namespace>
+   <ClassName>OpenApiClient</ClassName>
+   <CodeGenerator>NSwagCSharp</CodeGenerator>
+   <Options>/UseBaseUrl:false /GenerateClientInterfaces:true</Options>
+ </OpenApiReference>
+</ItemGroup>
+```
+
+
+## Usage
+
+The NSwag tooling generates the OpenAPI client during a prebuild step. Once your application is built,
+you can instantiate it using the class name as indicated in the project file.
+
+```c#
+namespace ApiConsumer
+{
+    class Program
+    {
+        static void Main(string[] args)
+        {
+            using (HttpClient httpClient = new HttpClient())
+            {
+                OpenApiClient openApiClient = new OpenApiClient(httpClient);
+
+                // IntelliSense is now available on `openApiClient`!
+            }
+        }
+    }
+}
+```
+
+Support for partial write requests can be enabled by leveraging the extensibility points of the generated client.
+
+```c#
+// Note that this class should be namespace in which NSwag generates the client. 
+namespace ApiConsumer.GeneratedCode
+{
+    public partial class OpenApiClient : JsonApiClient
+    {
+        partial void UpdateJsonSerializerSettings(JsonSerializerSettings settings)
+        {
+            SetSerializerSettingsForJsonApi(settings);
+        }
+    }
+}
+```
+
+You can now perform a write request by calling the `RegisterAttributesForRequest` method. Calling this method treats all attributes that contain their default value (<c>null</c> for reference types, <c>0</c> for integers, <c>false</c> for booleans, etc) as omitted unless explicitly listed to include them using the `alwaysIncludedAttributeSelectors` parameter.
+
+```c#
+// Program.cs
+static void Main(string[] args)
+{
+    using (HttpClient httpClient = new HttpClient())
+    {
+        OpenApiClient openApiClient = new OpenApiClient(httpClient);
+
+        var requestDocument = new ApiResourcePatchRequestDocument
+        {
+            Data = new ApiResourceDataInPatchRequest
+            {
+                Id = 543,
+                Type = ApiResourceResourceType.Airplanes,
+                Attributes = new ApiResourceAttributesInPatchRequest
+                {
+                    someNullableAttribute = "Value"
+                }
+            }
+        };
+
+        using (apiClient.RegisterAttributesForRequestDocument<ApiResourcePatchRequestDocument, ApiResourceDataInPatchRequest>(requestDocument, apiResource => apiResource.AnotherNullableAttribute)
+        {
+            await apiClient.PatchApiResourceAsync(543, requestDocument));
+
+            // The request will look like this:
+            //
+            // {
+            //   "data": {
+            //     "type": "apiResource",
+            //     "id": "543",
+            //     "attributes": {
+            //       "someNullableAttribute": "Value",
+            //       "anotherNullableAttribute": null,
+            //     }
+            //   }
+            // }
+        }
+
+    }
+}
+```
+

docs/usage/openapi/openapi.md renamed to docs/usage/openapi/openapi-generator.md

@@ -1,4 +1,4 @@
-# OpenAPI
+# OpenAPI generator
 
 You can describe your API with an OpenAPI specification using the [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) integration for JsonApiDotNetCore. 
 

docs/usage/openapi/openapiclient.md

@@ -23,8 +23,8 @@
 # [Caching](caching.md)
 
 # OpenAPI
-## [Specification Generator](openapi/openapi.md))
-## [Generated Client](openapi/openapiclient.md))
+## [Describing Your API](openapi/openapi-generator.md))
+## [Generating A Client](openapi/client-generator.md))
 
 # Extensibility
 ## [Layer Overview](extensibility/layer-overview.md)

docs/usage/toc.md

@@ -2,9 +2,9 @@
 using System.Collections.Generic;
 using System.Linq;
 using System.Reflection;
-using JsonApiDotNetCore.OpenApi.JsonApiMetadata;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Middleware;
+using JsonApiDotNetCore.OpenApi.JsonApiMetadata;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.Abstractions;
 using Microsoft.AspNetCore.Mvc.Controllers;

src/JsonApiDotNetCore.OpenApi/JsonApiActionDescriptorCollectionProvider.cs

@@ -2,10 +2,10 @@
 using System.Collections.Generic;
 using System.Linq;
 using System.Reflection;
-using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
-using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Middleware;
+using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
+using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
 using JsonApiDotNetCore.Resources.Annotations;
 
 namespace JsonApiDotNetCore.OpenApi.JsonApiMetadata

src/JsonApiDotNetCore.OpenApi/JsonApiMetadata/JsonApiEndpointMetadataProvider.cs

@@ -2,9 +2,9 @@
 using System.Collections.Generic;
 using System.Linq;
 using Humanizer;
+using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
-using JsonApiDotNetCore.Middleware;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
 using Microsoft.AspNetCore.Mvc.Controllers;

src/JsonApiDotNetCore.OpenApi/JsonApiOperationIdSelector.cs

@@ -2,10 +2,10 @@
 using System.Collections.Generic;
 using System.Linq;
 using Humanizer;
+using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
-using JsonApiDotNetCore.Configuration;
 
 namespace JsonApiDotNetCore.OpenApi
 {

src/JsonApiDotNetCore.OpenApi/JsonApiSchemaIdSelector.cs

@@ -1,10 +1,10 @@
 using System;
 using System.Linq;
 using System.Reflection;
+using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
 using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
-using JsonApiDotNetCore.Configuration;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
 
@@ -66,16 +66,9 @@ public OpenApiSchema GenerateSchema(Type type, SchemaRepository schemaRepository
                 return jsonApiDocumentSchema;
             }
 
-            OpenApiSchema schema;
-
-            if (IsJsonApiResourceDocument(type))
-            {
-                schema = GenerateResourceJsonApiDocumentSchema(type);
-            }
-            else
-            {
-                schema = _defaultSchemaGenerator.GenerateSchema(type, schemaRepository, memberInfo, parameterInfo);
-            }
+            OpenApiSchema schema = IsJsonApiResourceDocument(type)
+                ? GenerateResourceJsonApiDocumentSchema(type)
+                : _defaultSchemaGenerator.GenerateSchema(type, schemaRepository, memberInfo, parameterInfo);
 
             if (IsSingleNonPrimaryDataDocument(type))
             {

src/JsonApiDotNetCore.OpenApi/SwaggerComponents/JsonApiSchemaGenerator.cs

@@ -1,7 +1,7 @@
 using System;
 using System.Collections.Generic;
-using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
 using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
 using Microsoft.OpenApi.Models;
 using Newtonsoft.Json.Serialization;
 using Swashbuckle.AspNetCore.SwaggerGen;