Support NRT and MSV in required and nullable

docs/usage/openapi-client.md

@@ -2,46 +2,56 @@
 
 You can generate a JSON:API client in various programming languages from the [OpenAPI specification](https://swagger.io/specification/) file that JsonApiDotNetCore APIs provide.
 
-For C# .NET clients generated using [NSwag](https://github.com/RicoSuter/NSwag), we provide an additional package that introduces support for partial PATCH/POST requests. The issue here is that a property on a generated C# class being `null` could mean "set the value to `null` in the request" or "this is `null` because I never touched it".
+For C# .NET clients generated using [NSwag](https://github.com/RicoSuter/NSwag), we provide an additional package
+that introduces support for partial PATCH/POST requests. The concern here is that a property on a generated C# class
+being `null` could mean "set the value to `null` in the request" or "this is `null` because I never touched it".
 
 ## Getting started
 
 ### Visual Studio
 
-The easiest way to get started is by using the built-in capabilities of Visual Studio. The next steps describe how to generate a JSON:API client library and use our package.
+The easiest way to get started is by using the built-in capabilities of Visual Studio.
+The next steps describe how to generate a JSON:API client library and use our package.
 
 1.  In **Solution Explorer**, right-click your client project, select **Add** > **Service Reference** and choose **OpenAPI**.
 
 2.  On the next page, specify the OpenAPI URL to your JSON:API server, for example: `http://localhost:14140/swagger/v1/swagger.json`.
-    Optionally provide a class name and namespace and click **Finish**.
-    Visual Studio now downloads your swagger.json and updates your project file. This results in a pre-build step that generates the client code.
+    Specify `ExampleApiClient` as class name, optionally provide a namespace and click **Finish**.
+    Visual Studio now downloads your swagger.json and updates your project file.
+    This adds a pre-build step that generates the client code.
 
-    Tip: To later re-download swagger.json and regenerate the client code, right-click **Dependencies** > **Manage Connected Services** and click the **Refresh** icon.
-3.  Although not strictly required, we recommend to run package update now, which fixes some issues and removes the `Stream` parameter from generated calls.
+    > [!TIP]
+    > To later re-download swagger.json and regenerate the client code,
+    > right-click **Dependencies** > **Manage Connected Services** and click the **Refresh** icon.
 
-4.  Add some demo code that calls one of your JSON:API endpoints. For example:
+3.  Although not strictly required, we recommend to run package update now, which fixes some issues.
+
+4.  Add code that calls one of your JSON:API endpoints.
 
     ```c#
     using var httpClient = new HttpClient();
     var apiClient = new ExampleApiClient("http://localhost:14140", httpClient);
 
-    PersonCollectionResponseDocument getResponse =
-        await apiClient.GetPersonCollectionAsync();
+    PersonCollectionResponseDocument getResponse = await apiClient.GetPersonCollectionAsync();
 
     foreach (PersonDataInResponse person in getResponse.Data)
     {
-        Console.WriteLine($"Found user {person.Id} named " +
-            $"'{person.Attributes.FirstName} {person.Attributes.LastName}'.");
+        Console.WriteLine($"Found person {person.Id}: {person.Attributes.DisplayName}");
     }
     ```
 
 5.  Add our client package to your project:
 
-   ```
-   dotnet add package JsonApiDotNetCore.OpenApi.Client
-   ```
+    ```
+    dotnet add package JsonApiDotNetCore.OpenApi.Client
+    ```
+
+6.  Add the following glue code to connect our package with your generated code.
 
-6.  Add the following glue code to connect our package with your generated code. The code below assumes you specified `ExampleApiClient` as class name in step 2.
+    > [!NOTE]
+    > The class name must be the same as specified in step 2.
+    > If you also specified a namespace, put this class in the same namespace.
+    > For example, add `namespace GeneratedCode;` below the `using` lines.
 
     ```c#
     using JsonApiDotNetCore.OpenApi.Client;
@@ -56,6 +66,9 @@ The easiest way to get started is by using the built-in capabilities of Visual S
     }
     ```
 
+    > [!TIP]
+    > The project at src/Examples/JsonApiDotNetCoreExampleClient contains an enhanced version that logs the HTTP requests and responses.
+
 7.  Extend your demo code to send a partial PATCH request with the help of our package:
 
     ```c#
@@ -66,30 +79,43 @@ The easiest way to get started is by using the built-in capabilities of Visual S
             Id = "1",
             Attributes = new PersonAttributesInPatchRequest
             {
-                FirstName = "Jack"
+                LastName = "Doe"
             }
         }
     };
 
-    // This line results in sending "lastName: null" instead of omitting it.
-    using (apiClient.RegisterAttributesForRequestDocument<PersonPatchRequestDocument,
-        PersonAttributesInPatchRequest>(patchRequest, person => person.LastName))
+    // This line results in sending "firstName: null" instead of omitting it.
+    using (apiClient.WithPartialAttributeSerialization<PersonPatchRequestDocument, PersonAttributesInPatchRequest>(patchRequest,
+        person => person.FirstName))
     {
-        PersonPrimaryResponseDocument patchResponse =
-            await apiClient.PatchPersonAsync("1", patchRequest);
+        await TranslateAsync(async () => await apiClient.PatchPersonAsync(1, patchRequest));
 
         // The sent request looks like this:
         // {
         //   "data": {
         //     "type": "people",
         //     "id": "1",
         //     "attributes": {
-        //       "firstName": "Jack",
-        //       "lastName": null
+        //       "firstName": null,
+        //       "lastName": "Doe"
         //     }
         //   }
         // }
     }
+
+    static async Task<TResponse?> TranslateAsync<TResponse>(Func<Task<TResponse>> operation)
+        where TResponse : class
+    {
+        try
+        {
+            return await operation();
+        }
+        catch (ApiException exception) when (exception.StatusCode == 204)
+        {
+            // Workaround for https://github.com/RicoSuter/NSwag/issues/2499
+            return null;
+        }
+    }
     ```
 
 ### Other IDEs
@@ -100,12 +126,12 @@ Alternatively, the next section shows what to add to your client project file di
 
 ```xml
 <ItemGroup>
-  <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="3.0.0">
+  <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="7.0.11">
     <PrivateAssets>all</PrivateAssets>
     <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
   </PackageReference>
-  <PackageReference Include="Newtonsoft.Json" Version="12.0.2" />
-  <PackageReference Include="NSwag.ApiDescription.Client" Version="13.0.5">
+  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+  <PackageReference Include="NSwag.ApiDescription.Client" Version="13.20.0">
     <PrivateAssets>all</PrivateAssets>
     <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
   </PackageReference>

docs/usage/openapi.md

@@ -16,25 +16,26 @@ JsonApiDotNetCore provides an extension package that enables you to produce an [
     ```c#
     IMvcCoreBuilder mvcCoreBuilder = builder.Services.AddMvcCore();
 
+    // Include the mvcBuilder parameter.
     builder.Services.AddJsonApi<AppDbContext>(mvcBuilder: mvcCoreBuilder);
 
-    // Configures Swashbuckle for JSON:API.
+    // Configure Swashbuckle for JSON:API.
     builder.Services.AddOpenApi(mvcCoreBuilder);
 
     var app = builder.Build();
 
     app.UseRouting();
     app.UseJsonApi();
 
-    // Adds the Swashbuckle middleware.
+    // Add the Swashbuckle middleware.
     app.UseSwagger();
     ```
 
 By default, the OpenAPI specification will be available at `http://localhost:<port>/swagger/v1/swagger.json`.
 
 ## Documentation
 
-Swashbuckle also ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), tooling for a generated documentation page. This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Program.cs` file:
+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();

src/Examples/JsonApiDotNetCoreExampleClient/ExampleApiClient.cs

@@ -2,6 +2,8 @@
 using JsonApiDotNetCore.OpenApi.Client;
 using Newtonsoft.Json;
 
+// ReSharper disable UnusedParameterInPartialMethod
+
 namespace JsonApiDotNetCoreExampleClient;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Itself)]
@@ -11,6 +13,50 @@ partial void UpdateJsonSerializerSettings(JsonSerializerSettings settings)
     {
         SetSerializerSettingsForJsonApi(settings);
 
+        // Optional: Makes the JSON easier to read when logged.
         settings.Formatting = Formatting.Indented;
     }
+
+    // Optional: Log outgoing request to the console.
+    partial void PrepareRequest(HttpClient client, HttpRequestMessage request, string url)
+    {
+        using var _ = new UsingConsoleColor(ConsoleColor.Green);
+
+        Console.WriteLine($"--> {request}");
+        string? requestBody = request.Content?.ReadAsStringAsync().GetAwaiter().GetResult();
+
+        if (!string.IsNullOrEmpty(requestBody))
+        {
+            Console.WriteLine();
+            Console.WriteLine(requestBody);
+        }
+    }
+
+    // Optional: Log incoming response to the console.
+    partial void ProcessResponse(HttpClient client, HttpResponseMessage response)
+    {
+        using var _ = new UsingConsoleColor(ConsoleColor.Cyan);
+
+        Console.WriteLine($"<-- {response}");
+        string responseBody = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+
+        if (!string.IsNullOrEmpty(responseBody))
+        {
+            Console.WriteLine();
+            Console.WriteLine(responseBody);
+        }
+    }
+
+    private sealed class UsingConsoleColor : IDisposable
+    {
+        public UsingConsoleColor(ConsoleColor foregroundColor)
+        {
+            Console.ForegroundColor = foregroundColor;
+        }
+
+        public void Dispose()
+        {
+            Console.ResetColor();
+        }
+    }
 }

src/Examples/JsonApiDotNetCoreExampleClient/OpenAPIs/swagger.json

@@ -2051,6 +2051,10 @@
         "additionalProperties": false
       },
       "personAttributesInResponse": {
+        "required": [
+          "displayName",
+          "lastName"
+        ],
         "type": "object",
         "properties": {
           "firstName": {
@@ -2341,6 +2345,9 @@
         "additionalProperties": false
       },
       "tagAttributesInResponse": {
+        "required": [
+          "name"
+        ],
         "type": "object",
         "properties": {
           "name": {
@@ -2715,6 +2722,10 @@
         "additionalProperties": false
       },
       "todoItemAttributesInResponse": {
+        "required": [
+          "description",
+          "priority"
+        ],
         "type": "object",
         "properties": {
           "description": {
@@ -2970,6 +2981,9 @@
         "additionalProperties": false
       },
       "todoItemRelationshipsInResponse": {
+        "required": [
+          "owner"
+        ],
         "type": "object",
         "properties": {
           "owner": {

src/Examples/JsonApiDotNetCoreExampleClient/Program.cs

@@ -1,26 +1,47 @@
-namespace JsonApiDotNetCoreExampleClient;
+using JsonApiDotNetCoreExampleClient;
 
-internal static class Program
-{
-    private const string BaseUrl = "http://localhost:14140";
+using var httpClient = new HttpClient();
+var apiClient = new ExampleApiClient("http://localhost:14140", httpClient);
 
-    private static async Task Main()
-    {
-        using var httpClient = new HttpClient();
+PersonCollectionResponseDocument getResponse = await apiClient.GetPersonCollectionAsync();
 
-        ExampleApiClient exampleApiClient = new(BaseUrl, httpClient);
+foreach (PersonDataInResponse person in getResponse.Data)
+{
+    Console.WriteLine($"Found person {person.Id}: {person.Attributes.DisplayName}");
+}
 
-        try
-        {
-            const int nonExistingId = int.MaxValue;
-            await exampleApiClient.DeletePersonAsync(nonExistingId);
-        }
-        catch (ApiException exception)
+var patchRequest = new PersonPatchRequestDocument
+{
+    Data = new PersonDataInPatchRequest
+    {
+        Id = "1",
+        Attributes = new PersonAttributesInPatchRequest
         {
-            Console.WriteLine(exception.Response);
+            LastName = "Doe"
         }
+    }
+};
 
-        Console.WriteLine("Press any key to close.");
-        Console.ReadKey();
+// This line results in sending "firstName: null" instead of omitting it.
+using (apiClient.WithPartialAttributeSerialization<PersonPatchRequestDocument, PersonAttributesInPatchRequest>(patchRequest, person => person.FirstName))
+{
+    await TranslateAsync(async () => await apiClient.PatchPersonAsync(1, patchRequest));
+}
+
+Console.WriteLine("Press any key to close.");
+Console.ReadKey();
+
+// ReSharper disable once UnusedLocalFunctionReturnValue
+static async Task<TResponse?> TranslateAsync<TResponse>(Func<Task<TResponse>> operation)
+    where TResponse : class
+{
+    try
+    {
+        return await operation();
+    }
+    catch (ApiException exception) when (exception.StatusCode == 204)
+    {
+        // Workaround for https://github.com/RicoSuter/NSwag/issues/2499
+        return null;
     }
 }

src/JsonApiDotNetCore.OpenApi.Client/Exceptions/ApiException.cs

@@ -14,7 +14,7 @@ public sealed class ApiException : Exception
 
     public IReadOnlyDictionary<string, IEnumerable<string>> Headers { get; }
 
-    public ApiException(string message, int statusCode, string? response, IReadOnlyDictionary<string, IEnumerable<string>> headers, Exception innerException)
+    public ApiException(string message, int statusCode, string? response, IReadOnlyDictionary<string, IEnumerable<string>> headers, Exception? innerException)
         : base($"{message}\n\nStatus: {statusCode}\nResponse: \n{response ?? "(null)"}", innerException)
     {
         StatusCode = statusCode;

src/JsonApiDotNetCore.OpenApi.Client/IJsonApiClient.cs

@@ -5,17 +5,19 @@ namespace JsonApiDotNetCore.OpenApi.Client;
 public interface IJsonApiClient
 {
     /// <summary>
-    /// Ensures correct serialization of attributes in a POST/PATCH Resource request body. In JSON:API, an omitted attribute indicates to ignore it, while an
-    /// attribute that is set to "null" means to clear it. This poses a problem because the serializer cannot distinguish between "you have explicitly set
-    /// this .NET property to null" vs "you didn't touch it, so it is null by default" when converting an instance to JSON. Therefore, 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 <paramref name="alwaysIncludedAttributeSelectors" />.
+    /// Ensures correct serialization of JSON:API attributes in the request body of a POST/PATCH request at a resource endpoint. Properties with default
+    /// values are omitted, unless explicitly included using <paramref name="alwaysIncludedAttributeSelectors" />
+    /// <para>
+    /// In JSON:API, an omitted attribute indicates to ignore it, while an attribute that is set to <c>null</c> means to clear it. This poses a problem,
+    /// because the serializer cannot distinguish between "you have explicitly set this .NET property to its default value" vs "you didn't touch it, so it
+    /// contains its default value" when converting to JSON.
+    /// </para>
     /// </summary>
     /// <param name="requestDocument">
-    /// The request document instance for which this registration applies.
+    /// The request document instance for which default values should be omitted.
     /// </param>
     /// <param name="alwaysIncludedAttributeSelectors">
-    /// Optional. A list of expressions to indicate which properties to unconditionally include in the JSON request body. For example:
+    /// Optional. A list of lambda expressions that indicate which properties to always include in the JSON request body. For example:
     /// <code><![CDATA[
     /// video => video.Title, video => video.Summary
     /// ]]></code>
@@ -28,9 +30,10 @@ public interface IJsonApiClient
     /// </typeparam>
     /// <returns>
     /// An <see cref="IDisposable" /> to clear the current registration. For efficient memory usage, it is recommended to wrap calls to this method in a
-    /// <c>using</c> statement, so the registrations are cleaned up after executing the request.
+    /// <c>using</c> statement, so the registrations are cleaned up after executing the request. After disposal, the client can be reused without the
+    /// registrations added earlier.
     /// </returns>
-    IDisposable RegisterAttributesForRequestDocument<TRequestDocument, TAttributesObject>(TRequestDocument requestDocument,
+    IDisposable WithPartialAttributeSerialization<TRequestDocument, TAttributesObject>(TRequestDocument requestDocument,
         params Expression<Func<TAttributesObject, object?>>[] alwaysIncludedAttributeSelectors)
         where TRequestDocument : class;
 }