OpenAPI support for Atomic Operations

This PR adds full support for using atomic operations with OpenAPI. Tests and examples using NSwag and Kiota are provided.

Various types have been renamed, which heavily affects generated clients. For example, personPatchRequestDocument is now updatePersonRequestDocument, and personAttributesInPostRequest has become attributesInCreatePersonRequest. These renames were done because atomic operations are reusing existing schemas. As we're breaking big now (sorry), I did some extra cleanups in schema names. The easiest way to overcome that is to use target-typed new.

Both id and lid are exposed in all request types, to avoid an explosion of schema types. But this only happens when an operations controller is found. The effect is that you can send a lid in a post-resource request (which will be rejected by the server). Because of the id/lid distinction, separate schemas are generated for resource identifiers in requests and responses (so staffMemberIdentifier is replaced by staffMemberIdentifierInRequest and staffMemberIdentifierInResponse).

Another change is that the id property has moved from the abstract dataInResponse type into the resource-specific derived types. The effect is that you first need to upcast/type-check before getting access to the id.

Both NSwag and Kiota choke on the quotes in the application/vnd.api+json; ext="https://jsonapi.org/ext/atomic" media type, generating code that doesn't compile. Therefore, OpenAPI uses the relaxed variant introduced in #1553.

The exposed operations in OpenAPI are based on the GenerateControllerEndpoints by default, but can be customized using your own IAtomicOperationFilter, a new feature that was introduced in #1561.

The generation of id/lid properties takes ClientIdGenerationMode into account for create-resource operations. Likewise, get-only or set-only attribute properties are hidden in the appropriate schemas.

There is currently no way to send null/default attribute values in an operations request with NSwag. This is tracked at #1577.

Example usage:

var operationsRequest = new OperationsRequestDocument
{
    Atomic_operations =
    [
        new CreateTagOperation
        {
            Data = new DataInCreateTagRequest
            {
                Lid = "new-tag",
                Attributes = new AttributesInCreateTagRequest
                {
                    Name = "Housekeeping"
                }
            }
        },
        new CreatePersonOperation
        {
            Data = new DataInCreatePersonRequest
            {
                Lid = "new-person",
                Attributes = new AttributesInCreatePersonRequest
                {
                    LastName = "Cinderella"
                }
            }
        },
        new CreateTodoItemOperation
        {
            Data = new DataInCreateTodoItemRequest
            {
                Lid = "new-todo-item",
                Attributes = new AttributesInCreateTodoItemRequest
                {
                    Description = "Put out the garbage",
                    Priority = TodoItemPriority.Medium
                },
                Relationships = new RelationshipsInCreateTodoItemRequest
                {
                    Owner = new ToOnePersonInRequest
                    {
                        Data = new PersonIdentifierInRequest
                        {
                            Lid = "new-person"
                        }
                    },
                    Tags = new ToManyTagInRequest
                    {
                        Data =
                        [
                            new TagIdentifierInRequest
                            {
                                Lid = "new-tag"
                            }
                        ]
                    }
                }
            }
        },
        new UpdateTodoItemAssigneeRelationshipOperation
        {
            Ref = new TodoItemAssigneeRelationshipIdentifier
            {
                Lid = "new-todo-item"
            },
            Data = new PersonIdentifierInRequest
            {
                Lid = "new-person"
            }
        }
    ]
};

ApiResponse<OperationsResponseDocument> operationsResponse =
    await _apiClient.PostOperationsAsync(operationsRequest, cancellationToken);

var newTodoItem = (TodoItemDataInResponse)operationsResponse.Result.Atomic_results.ElementAt(2).Data!;
Console.WriteLine($"Created todo-item with ID {newTodoItem.Id}: {newTodoItem.Attributes!.Description}.");

Closes #1060.

QUALITY CHECKLIST

[x] Changes implemented in code
[x] Complies with our contributing guidelines
[x] Adapted tests
[x] Documentation updated

json-api-dotnet / JsonApiDotNetCore

OpenAPI support for Atomic Operations #1580

QUALITY CHECKLIST

Codecov Report