openapi: include headers

src/Examples/JsonApiDotNetCoreExampleClient/JsonApiDotNetCoreExampleClient.csproj

@@ -25,7 +25,7 @@
 
   <ItemGroup>
     <OpenApiReference Include="..\JsonApiDotNetCoreExample\GeneratedSwagger\JsonApiDotNetCoreExample.json" CodeGenerator="NSwagCSharp" ClassName="ExampleApiClient">
-      <Options>/GenerateExceptionClasses:false /AdditionalNamespaceUsages:JsonApiDotNetCore.OpenApi.Client.Exceptions</Options>
+      <Options>/GenerateExceptionClasses:false /WrapResponses:true /GenerateResponseClasses:false /ResponseClass:ApiResponse /AdditionalNamespaceUsages:JsonApiDotNetCore.OpenApi.Client</Options>
     </OpenApiReference>
   </ItemGroup>
 </Project>

src/Examples/JsonApiDotNetCoreExampleClient/Program.cs

@@ -1,5 +1,7 @@
+using System.Net;
 using JsonApiDotNetCore.OpenApi.Client;
 using JsonApiDotNetCoreExampleClient;
+using Microsoft.Net.Http.Headers;
 
 #if DEBUG
 using var httpClient = new HttpClient(new ColoredConsoleLogDelegatingHandler
@@ -12,17 +14,17 @@
 
 var apiClient = new ExampleApiClient(httpClient);
 
-PersonCollectionResponseDocument getResponse = await apiClient.GetPersonCollectionAsync(new Dictionary<string, string?>
+ApiResponse<PersonCollectionResponseDocument?> getResponse1 = await GetPersonCollectionAsync(apiClient, null);
+ApiResponse<PersonCollectionResponseDocument?> getResponse2 = await GetPersonCollectionAsync(apiClient, getResponse1.Headers[HeaderNames.ETag].First());
+
+if (getResponse2 is { StatusCode: (int)HttpStatusCode.NotModified, Result: null })
 {
-    ["filter"] = "has(assignedTodoItems)",
-    ["sort"] = "-lastName",
-    ["page[size]"] = "5",
-    ["include"] = "assignedTodoItems.tags"
-});
+    Console.WriteLine("The HTTP response hasn't changed, so no response body was returned.");
+}
 
-foreach (PersonDataInResponse person in getResponse.Data)
+foreach (PersonDataInResponse person in getResponse1.Result!.Data)
 {
-    PrintPerson(person, getResponse.Included);
+    PrintPerson(person, getResponse1.Result.Included);
 }
 
 var patchRequest = new PersonPatchRequestDocument
@@ -47,6 +49,17 @@
 Console.WriteLine("Press any key to close.");
 Console.ReadKey();
 
+static Task<ApiResponse<PersonCollectionResponseDocument?>> GetPersonCollectionAsync(ExampleApiClient apiClient, string? ifNoneMatch)
+{
+    return ApiResponse.TranslateAsync(() => apiClient.GetPersonCollectionAsync(new Dictionary<string, string?>
+    {
+        ["filter"] = "has(assignedTodoItems)",
+        ["sort"] = "-lastName",
+        ["page[size]"] = "5",
+        ["include"] = "assignedTodoItems.tags"
+    }, ifNoneMatch));
+}
+
 static void PrintPerson(PersonDataInResponse person, ICollection<DataInResponse> includes)
 {
     ToManyTodoItemInResponse assignedTodoItems = person.Relationships.AssignedTodoItems;

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

@@ -3,7 +3,7 @@
 // We cannot rely on generating ApiException as soon as we are generating multiple clients, see https://github.com/RicoSuter/NSwag/issues/2839#issuecomment-776647377.
 // Instead, we configure NSwag to point to the exception below in the generated code.
 
-namespace JsonApiDotNetCore.OpenApi.Client.Exceptions;
+namespace JsonApiDotNetCore.OpenApi.Client;
 
 [UsedImplicitly(ImplicitUseTargetFlags.Members)]
 public class ApiException(string message, int statusCode, string? response, IReadOnlyDictionary<string, IEnumerable<string>> headers, Exception? innerException)

src/JsonApiDotNetCore.OpenApi.Client/ApiResponse.cs

@@ -1,13 +1,15 @@
+using System.Net;
 using JetBrains.Annotations;
-using JsonApiDotNetCore.OpenApi.Client.Exceptions;
-
-#pragma warning disable AV1008 // Class should not be static
 
 namespace JsonApiDotNetCore.OpenApi.Client;
 
 [PublicAPI]
-public static class ApiResponse
+public class ApiResponse(int statusCode, IReadOnlyDictionary<string, IEnumerable<string>> headers)
 {
+    public int StatusCode { get; private set; } = statusCode;
+
+    public IReadOnlyDictionary<string, IEnumerable<string>> Headers { get; private set; } = headers;
+
     public static async Task<TResponse?> TranslateAsync<TResponse>(Func<Task<TResponse>> operation)
         where TResponse : class
     {
@@ -17,7 +19,7 @@ public static class ApiResponse
         {
             return await operation().ConfigureAwait(false);
         }
-        catch (ApiException exception) when (exception.StatusCode == 204)
+        catch (ApiException exception) when (exception.StatusCode is (int)HttpStatusCode.NoContent or (int)HttpStatusCode.NotModified)
         {
             // Workaround for https://github.com/RicoSuter/NSwag/issues/2499
             return null;
@@ -32,9 +34,46 @@ public static async Task TranslateAsync(Func<Task> operation)
         {
             await operation().ConfigureAwait(false);
         }
-        catch (ApiException exception) when (exception.StatusCode == 204)
+        catch (ApiException exception) when (exception.StatusCode is (int)HttpStatusCode.NoContent or (int)HttpStatusCode.NotModified)
+        {
+            // Workaround for https://github.com/RicoSuter/NSwag/issues/2499
+        }
+    }
+
+    public static async Task<ApiResponse<TResult?>> TranslateAsync<TResult>(Func<Task<ApiResponse<TResult>>> operation)
+        where TResult : class
+    {
+        ArgumentGuard.NotNull(operation);
+
+        try
+        {
+            return (await operation().ConfigureAwait(false))!;
+        }
+        catch (ApiException exception) when (exception.StatusCode is (int)HttpStatusCode.NoContent or (int)HttpStatusCode.NotModified)
+        {
+            // Workaround for https://github.com/RicoSuter/NSwag/issues/2499
+            return new ApiResponse<TResult?>(exception.StatusCode, exception.Headers, null);
+        }
+    }
+
+    public static async Task<ApiResponse> TranslateAsync(Func<Task<ApiResponse>> operation)
+    {
+        ArgumentGuard.NotNull(operation);
+
+        try
+        {
+            return await operation().ConfigureAwait(false);
+        }
+        catch (ApiException exception) when (exception.StatusCode is (int)HttpStatusCode.NoContent or (int)HttpStatusCode.NotModified)
         {
             // Workaround for https://github.com/RicoSuter/NSwag/issues/2499
+            return new ApiResponse(exception.StatusCode, exception.Headers);
         }
     }
 }
+
+[PublicAPI]
+public class ApiResponse<TResult>(int statusCode, IReadOnlyDictionary<string, IEnumerable<string>> headers, TResult result) : ApiResponse(statusCode, headers)
+{
+    public TResult Result { get; private set; } = result;
+}

src/JsonApiDotNetCore.OpenApi/OpenApiEndpointConvention.cs

@@ -147,8 +147,11 @@ private static IEnumerable<HttpStatusCode> GetSuccessStatusCodesForEndpoint(Json
     {
         return endpoint switch
         {
-            JsonApiEndpoint.GetCollection or JsonApiEndpoint.GetSingle or JsonApiEndpoint.GetSecondary or JsonApiEndpoint.GetRelationship
-                => [HttpStatusCode.OK],
+            JsonApiEndpoint.GetCollection or JsonApiEndpoint.GetSingle or JsonApiEndpoint.GetSecondary or JsonApiEndpoint.GetRelationship =>
+            [
+                HttpStatusCode.OK,
+                HttpStatusCode.NotModified
+            ],
             JsonApiEndpoint.Post =>
             [
                 HttpStatusCode.Created,

src/JsonApiDotNetCore.OpenApi/SwaggerComponents/JsonApiOperationDocumentationFilter.cs

@@ -7,6 +7,7 @@
 using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Resources.Annotations;
 using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.Net.Http.Headers;
 using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Models;
 using Swashbuckle.AspNetCore.SwaggerGen;
@@ -30,6 +31,7 @@ internal sealed class JsonApiOperationDocumentationFilter : IOperationFilter
         "Compare the returned ETag HTTP header with an earlier one to determine if the response has changed since it was fetched.";
 
     private const string TextCompletedSuccessfully = "The operation completed successfully.";
+    private const string TextNotModified = "The fingerprint of the HTTP response matches one of the ETags from the incoming If-None-Match header.";
     private const string TextQueryStringBad = "The query string is invalid.";
     private const string TextRequestBodyBad = "The request body is missing or malformed.";
     private const string TextQueryStringOrRequestBodyBad = "The query string is invalid or the request body is missing or malformed.";
@@ -162,16 +164,25 @@ private static void ApplyGetPrimary(OpenApiOperation operation, ResourceType res
                 SetOperationSummary(operation, $"Retrieves a collection of {resourceType} without returning them.");
                 SetOperationRemarks(operation, TextCompareETag);
                 SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully);
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+                SetResponseHeaderContentLength(operation.Responses, HttpStatusCode.OK);
+                SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
             }
             else
             {
                 SetOperationSummary(operation, $"Retrieves a collection of {resourceType}.");
 
                 SetResponseDescription(operation.Responses, HttpStatusCode.OK,
                     $"Successfully returns the found {resourceType}, or an empty array if none were found.");
+
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+                SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
             }
 
             AddQueryStringParameters(operation, false);
+            AddRequestHeaderIfNoneMatch(operation);
             SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextQueryStringBad);
         }
         else if (operation.Parameters.Count == 1)
@@ -183,15 +194,23 @@ private static void ApplyGetPrimary(OpenApiOperation operation, ResourceType res
                 SetOperationSummary(operation, $"Retrieves an individual {singularName} by its identifier without returning it.");
                 SetOperationRemarks(operation, TextCompareETag);
                 SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully);
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+                SetResponseHeaderContentLength(operation.Responses, HttpStatusCode.OK);
+                SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
             }
             else
             {
                 SetOperationSummary(operation, $"Retrieves an individual {singularName} by its identifier.");
                 SetResponseDescription(operation.Responses, HttpStatusCode.OK, $"Successfully returns the found {singularName}.");
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+                SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+                SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
             }
 
             SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularName} to retrieve.");
             AddQueryStringParameters(operation, false);
+            AddRequestHeaderIfNoneMatch(operation);
             SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextQueryStringBad);
             SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularName} does not exist.");
         }
@@ -208,6 +227,8 @@ private void ApplyPostResource(OpenApiOperation operation, ResourceType resource
         SetResponseDescription(operation.Responses, HttpStatusCode.Created,
             $"The {singularName} was successfully created, which resulted in additional changes. The newly created {singularName} is returned.");
 
+        SetResponseHeaderLocation(operation.Responses, HttpStatusCode.Created);
+
         SetResponseDescription(operation.Responses, HttpStatusCode.NoContent,
             $"The {singularName} was successfully created, which did not result in additional changes.");
 
@@ -271,6 +292,10 @@ relationship is HasOneAttribute
 
             SetOperationRemarks(operation, TextCompareETag);
             SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+            SetResponseHeaderContentLength(operation.Responses, HttpStatusCode.OK);
+            SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
         }
         else
         {
@@ -280,10 +305,15 @@ relationship is HasOneAttribute
                 relationship is HasOneAttribute
                     ? $"Successfully returns the found {rightName}, or <c>null</c> if it was not found."
                     : $"Successfully returns the found {rightName}, or an empty array if none were found.");
+
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+            SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
         }
 
         SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} whose related {rightName} to retrieve.");
         AddQueryStringParameters(operation, false);
+        AddRequestHeaderIfNoneMatch(operation);
         SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextQueryStringBad);
         SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularLeftName} does not exist.");
     }
@@ -303,6 +333,10 @@ relationship is HasOneAttribute
 
             SetOperationRemarks(operation, TextCompareETag);
             SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully);
+            SetResponseHeaderContentLength(operation.Responses, HttpStatusCode.OK);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+            SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
         }
         else
         {
@@ -313,10 +347,15 @@ relationship is HasOneAttribute
                 relationship is HasOneAttribute
                     ? $"Successfully returns the found {singularRightName} {ident}, or <c>null</c> if it was not found."
                     : $"Successfully returns the found {singularRightName} {ident}, or an empty array if none were found.");
+
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
+            SetResponseDescription(operation.Responses, HttpStatusCode.NotModified, TextNotModified);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.NotModified);
         }
 
         SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} whose related {singularRightName} {ident} to retrieve.");
         AddQueryStringParameters(operation, true);
+        AddRequestHeaderIfNoneMatch(operation);
         SetResponseDescription(operation.Responses, HttpStatusCode.BadRequest, TextQueryStringBad);
         SetResponseDescription(operation.Responses, HttpStatusCode.NotFound, $"The {singularLeftName} does not exist.");
     }
@@ -420,6 +459,58 @@ private static void SetRequestBodyDescription(OpenApiRequestBody requestBody, st
     }
 
     private static void SetResponseDescription(OpenApiResponses responses, HttpStatusCode statusCode, string description)
+    {
+        OpenApiResponse response = GetOrAddResponse(responses, statusCode);
+        response.Description = XmlCommentsTextHelper.Humanize(description);
+    }
+
+    private static void SetResponseHeaderETag(OpenApiResponses responses, HttpStatusCode statusCode)
+    {
+        OpenApiResponse response = GetOrAddResponse(responses, statusCode);
+
+        response.Headers[HeaderNames.ETag] = new OpenApiHeader
+        {
+            Description = "A fingerprint of the HTTP response, which can be used in an If-None-Match header to only fetch changes.",
+            Required = true,
+            Schema = new OpenApiSchema
+            {
+                Type = "string"
+            }
+        };
+    }
+
+    private static void SetResponseHeaderContentLength(OpenApiResponses responses, HttpStatusCode statusCode)
+    {
+        OpenApiResponse response = GetOrAddResponse(responses, statusCode);
+
+        response.Headers[HeaderNames.ContentLength] = new OpenApiHeader
+        {
+            Description = "Size of the HTTP response body, in bytes.",
+            Required = true,
+            Schema = new OpenApiSchema
+            {
+                Type = "integer"
+            }
+        };
+    }
+
+    private static void SetResponseHeaderLocation(OpenApiResponses responses, HttpStatusCode statusCode)
+    {
+        OpenApiResponse response = GetOrAddResponse(responses, statusCode);
+
+        response.Headers[HeaderNames.Location] = new OpenApiHeader
+        {
+            Description = "The URL at which the newly created JSON:API resource can be retrieved.",
+            Required = true,
+            Schema = new OpenApiSchema
+            {
+                Type = "string",
+                Format = "uri"
+            }
+        };
+    }
+
+    private static OpenApiResponse GetOrAddResponse(OpenApiResponses responses, HttpStatusCode statusCode)
     {
         string responseCode = ((int)statusCode).ToString();
 
@@ -429,7 +520,7 @@ private static void SetResponseDescription(OpenApiResponses responses, HttpStatu
             responses.Add(responseCode, response);
         }
 
-        response.Description = XmlCommentsTextHelper.Humanize(description);
+        return response;
     }
 
     private static void AddQueryStringParameters(OpenApiOperation operation, bool isRelationshipEndpoint)
@@ -462,4 +553,18 @@ private static void AddQueryStringParameters(OpenApiOperation operation, bool is
             Description = isRelationshipEndpoint ? RelationshipQueryStringParameters : ResourceQueryStringParameters
         });
     }
+
+    private static void AddRequestHeaderIfNoneMatch(OpenApiOperation operation)
+    {
+        operation.Parameters.Add(new OpenApiParameter
+        {
+            In = ParameterLocation.Header,
+            Name = "If-None-Match",
+            Description = "A list of ETags, resulting in HTTP status 304 without a body, if one of them matches the current fingerprint.",
+            Schema = new OpenApiSchema
+            {
+                Type = "string"
+            }
+        });
+    }
 }