Merge pull request #1580 from json-api-dotnet/openapi-operations

OpenAPI support for Atomic Operations

Author: bkoelman

.config/dotnet-tools.json

@@ -6,31 +6,36 @@
       "version": "2024.1.4",
       "commands": [
         "jb"
-      ]
+      ],
+      "rollForward": false
     },
     "regitlint": {
       "version": "6.3.12",
       "commands": [
         "regitlint"
-      ]
+      ],
+      "rollForward": false
     },
     "dotnet-reportgenerator-globaltool": {
       "version": "5.3.6",
       "commands": [
         "reportgenerator"
-      ]
+      ],
+      "rollForward": false
     },
     "docfx": {
       "version": "2.76.0",
       "commands": [
         "docfx"
-      ]
+      ],
+      "rollForward": false
     },
     "microsoft.openapi.kiota": {
-      "version": "1.14.0",
+      "version": "1.15.0",
       "commands": [
         "kiota"
-      ]
+      ],
+      "rollForward": false
     }
   }
 }

CSharpGuidelinesAnalyzer.config

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <cSharpGuidelinesAnalyzerSettings>
   <setting rule="AV1561" name="MaxParameterCount" value="6" />
-  <setting rule="AV1561" name="MaxConstructorParameterCount" value="13" />
+  <setting rule="AV1561" name="MaxConstructorParameterCount" value="15" />
 </cSharpGuidelinesAnalyzerSettings>

docs/usage/openapi-client.md

@@ -67,7 +67,7 @@ The following steps describe how to generate and use a JSON:API client in C#, us
 5.  Add the following line inside the **OpenApiReference** section in your project file:
 
     ```xml
-    <Options>/GenerateExceptionClasses:false /AdditionalNamespaceUsages:JsonApiDotNetCore.OpenApi.Client.NSwag</Options>
+    <Options>/GenerateExceptionClasses:false /GenerateNullableReferenceTypes:true /GenerateOptionalPropertiesAsNullable:true /GenerateOptionalParameters:true /AdditionalNamespaceUsages:JsonApiDotNetCore.OpenApi.Client.NSwag</Options>
     ```
 
 6.  Add the following glue code to connect our package with your generated code.
@@ -105,31 +105,32 @@ The following steps describe how to generate and use a JSON:API client in C#, us
 
     foreach (var person in getResponse.Data)
     {
-        Console.WriteLine($"Found person {person.Id}: {person.Attributes.DisplayName}");
+        Console.WriteLine($"Found person {person.Id}: {person.Attributes!.DisplayName}");
     }
     ```
 
 8.  Extend your demo code to send a partial PATCH request with the help of our package:
 
     ```c#
-    var patchRequest = new PersonPatchRequestDocument
+    var updatePersonRequest = new UpdatePersonRequestDocument
     {
-        Data = new PersonDataInPatchRequest
+        Data = new DataInUpdatePersonRequest
         {
             Id = "1",
-            Attributes = new PersonAttributesInPatchRequest
+            Attributes = new AttributesInUpdatePersonRequest
             {
                 LastName = "Doe"
             }
         }
     };
 
     // This line results in sending "firstName: null" instead of omitting it.
-    using (apiClient.WithPartialAttributeSerialization<PersonPatchRequestDocument, PersonAttributesInPatchRequest>(patchRequest,
-        person => person.FirstName))
+    using (apiClient.WithPartialAttributeSerialization<UpdatePersonRequestDocument, AttributesInUpdatePersonRequest>(
+        updatePersonRequest, person => person.FirstName))
     {
         // Workaround for https://github.com/RicoSuter/NSwag/issues/2499.
-        await ApiResponse.TranslateAsync(() => apiClient.PatchPersonAsync(patchRequest.Data.Id, null, patchRequest));
+        await ApiResponse.TranslateAsync(() =>
+            apiClient.PatchPersonAsync(updatePersonRequest.Data.Id, updatePersonRequest));
 
         // The sent request looks like this:
         // {
@@ -171,6 +172,7 @@ Alternatively, the following section shows what to add to your client project fi
       <CodeGenerator>NSwagCSharp</CodeGenerator>
       <ClassName>ExampleApiClient</ClassName>
       <OutputPath>ExampleApiClient.cs</OutputPath>
+      <Options>/GenerateExceptionClasses:false /GenerateNullableReferenceTypes:true /GenerateOptionalPropertiesAsNullable:true /GenerateOptionalParameters:true /AdditionalNamespaceUsages:JsonApiDotNetCore.OpenApi.Client.NSwag</Options>
   </OpenApiReference>
 </ItemGroup>
 ```
@@ -184,7 +186,7 @@ To generate your C# client, install the Kiota tool by following the steps at htt
 Next, generate client code by running the [command line tool](https://learn.microsoft.com/en-us/openapi/kiota/using#client-generation). For example:
 
 ```
-dotnet kiota generate --language CSharp --class-name ExampleApiClient --output ./GeneratedCode --backing-store --exclude-backward-compatible --clean-output --clear-cache --openapi ..\JsonApiDotNetCoreExample\GeneratedSwagger\JsonApiDotNetCoreExample.json
+dotnet kiota generate --language CSharp --class-name ExampleApiClient --output ./GeneratedCode --backing-store --exclude-backward-compatible --clean-output --clear-cache --openapi http://localhost:14140/swagger/v1/swagger.json
 ```
 
 > [!CAUTION]
@@ -216,7 +218,7 @@ For example, the following section puts the generated code in a namespace and ge
 </OpenApiReference>
 ```
 
-Likewise, you can enable nullable reference types by adding `/GenerateNullableReferenceTypes:true`, optionally combined with `/GenerateOptionalParameters:true`.
+Likewise, you can enable nullable reference types by adding `/GenerateNullableReferenceTypes:true /GenerateOptionalPropertiesAsNullable:true /GenerateOptionalParameters:true`.
 
 # [Kiota](#tab/kiota)
 
@@ -256,9 +258,9 @@ NSwag needs extra settings to make response headers accessible. Specify the foll
 This enables the following code, which is explained below:
 
 ```c#
-var getResponse = await ApiResponse.TranslateAsync(() => apiClient.GetPersonCollectionAsync(null, null));
+var getResponse = await ApiResponse.TranslateAsync(() => apiClient.GetPersonCollectionAsync());
 string eTag = getResponse.Headers["ETag"].Single();
-Console.WriteLine($"Retrieved {getResponse.Result.Data.Count} people.");
+Console.WriteLine($"Retrieved {getResponse.Result?.Data.Count ?? 0} people.");
 
 // wait some time...
 
@@ -295,3 +297,27 @@ Due to a [bug in Kiota](https://github.com/microsoft/kiota/issues/4190), a try/c
 For a full example, see the [example project](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/openapi/src/Examples/OpenApiKiotaClientExample).
 
 ---
+
+## Atomic operations
+
+# [NSwag](#tab/nswag)
+
+[Atomic operations](~/usage/writing/bulk-batch-operations.md) are fully supported.
+The [example project](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/openapi/src/Examples/OpenApiNSwagClientExample)
+demonstrates how to use them. It uses local IDs to:
+- Create a new tag
+- Create a new person
+- Create a new todo-item, tagged with the new tag, and owned by the new person
+- Assign the todo-item to the created person
+
+# [Kiota](#tab/kiota)
+
+[Atomic operations](~/usage/writing/bulk-batch-operations.md) are fully supported.
+See the [example project](https://github.com/json-api-dotnet/JsonApiDotNetCore/tree/openapi/src/Examples/OpenApiKiotaClientExample)
+demonstrates how to use them. It uses local IDs to:
+- Create a new tag
+- Create a new person
+- Create a new todo-item, tagged with the new tag, and owned by the new person
+- Assign the todo-item to the created person
+
+---