openapi: include ETag/Location headers

Author: verdie-g

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;
@@ -162,13 +163,15 @@ 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);
             }
             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);
             }
 
             AddQueryStringParameters(operation, false);
@@ -183,11 +186,13 @@ 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);
             }
             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);
             }
 
             SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularName} to retrieve.");
@@ -207,6 +212,7 @@ 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 +277,7 @@ relationship is HasOneAttribute
 
             SetOperationRemarks(operation, TextCompareETag);
             SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
         }
         else
         {
@@ -280,6 +287,7 @@ 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);
         }
 
         SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} whose related {rightName} to retrieve.");
@@ -303,6 +311,7 @@ relationship is HasOneAttribute
 
             SetOperationRemarks(operation, TextCompareETag);
             SetResponseDescription(operation.Responses, HttpStatusCode.OK, TextCompletedSuccessfully);
+            SetResponseHeaderETag(operation.Responses, HttpStatusCode.OK);
         }
         else
         {
@@ -313,6 +322,7 @@ 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);
         }
 
         SetParameterDescription(operation.Parameters[0], $"The identifier of the {singularLeftName} whose related {singularRightName} {ident} to retrieve.");
@@ -420,6 +430,31 @@ private static void SetRequestBodyDescription(OpenApiRequestBody requestBody, st
     }
 
     private static void SetResponseDescription(OpenApiResponses responses, HttpStatusCode statusCode, string description)
+    {
+        OpenApiResponse response = GetOrCreateResponse(responses, statusCode);
+        response.Description = XmlCommentsTextHelper.Humanize(description);
+    }
+
+    private static void SetResponseHeaderETag(OpenApiResponses responses, HttpStatusCode statusCode)
+    {
+        OpenApiResponse response = GetOrCreateResponse(responses, statusCode);
+        response.Headers[HeaderNames.ETag] = new OpenApiHeader
+        {
+            Description = "ETag identifying the version of the fetched resource.",
+            Example = new OpenApiString("\"33a64df551425fcc55e4d42a148795d9f25f89d4\""),
+        };
+    }
+
+    private static void SetResponseHeaderLocation(OpenApiResponses responses, HttpStatusCode statusCode)
+    {
+        OpenApiResponse response = GetOrCreateResponse(responses, statusCode);
+        response.Headers[HeaderNames.Location] = new OpenApiHeader
+        {
+            Description = "Location of the newly created resource.",
+        };
+    }
+
+    private static OpenApiResponse GetOrCreateResponse(OpenApiResponses responses, HttpStatusCode statusCode)
     {
         string responseCode = ((int)statusCode).ToString();
 
@@ -429,7 +464,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)

test/OpenApiTests/DocComments/DocCommentsTests.cs

@@ -76,6 +76,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(2);
                     responseElement.Should().HaveProperty("200.description", "Successfully returns the found skyscrapers, or an empty array if none were found.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                 });
             });
@@ -96,6 +98,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(2);
                     responseElement.Should().HaveProperty("200.description", "The operation completed successfully.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                 });
             });
@@ -115,6 +119,7 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(5);
                     responseElement.Should().HaveProperty("201.description", "The skyscraper was successfully created, which resulted in additional changes. The newly created skyscraper is returned.");
+                    responseElement.Should().HaveProperty("201.headers.Location.description", "Location of the newly created resource.");
                     responseElement.Should().HaveProperty("204.description", "The skyscraper was successfully created, which did not result in additional changes.");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid or the request body is missing or malformed.");
                     responseElement.Should().HaveProperty("409.description", "A resource type in the request body is incompatible.");
@@ -142,6 +147,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "Successfully returns the found skyscraper.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -165,6 +172,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "The operation completed successfully.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -236,6 +245,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "Successfully returns the found elevator, or `null` if it was not found.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -259,6 +270,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "The operation completed successfully.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -284,6 +297,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "Successfully returns the found elevator identity, or `null` if it was not found.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -307,6 +322,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "The operation completed successfully.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -355,6 +372,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "Successfully returns the found spaces, or an empty array if none were found.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -378,6 +397,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "The operation completed successfully.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -403,6 +424,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "Successfully returns the found space identities, or an empty array if none were found.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });
@@ -426,6 +449,8 @@ public async Task Endpoints_are_documented()
                 {
                     responseElement.EnumerateObject().ShouldHaveCount(3);
                     responseElement.Should().HaveProperty("200.description", "The operation completed successfully.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.description", "ETag identifying the version of the fetched resource.");
+                    responseElement.Should().HaveProperty("200.headers.ETag.example", "\"33a64df551425fcc55e4d42a148795d9f25f89d4\"");
                     responseElement.Should().HaveProperty("400.description", "The query string is invalid.");
                     responseElement.Should().HaveProperty("404.description", "The skyscraper does not exist.");
                 });