From 072ed6daa988f22da26dd4f0add8ab459c1fef54 Mon Sep 17 00:00:00 2001
From: Bart Koelman <10324372+bkoelman@users.noreply.github.com>
Date: Fri, 27 Oct 2023 03:08:06 +0200
Subject: [PATCH] Fix generated documentation on relationships and enum
 properties

---
 .../ResourceFieldObjectSchemaBuilder.cs       |  9 +--
 .../DocComments/DocCommentsTests.cs           | 59 +++++++++++++++++--
 2 files changed, 58 insertions(+), 10 deletions(-)

diff --git a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs
index 881638c370..4011c357ac 100644
--- a/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs
+++ b/src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs
@@ -154,7 +154,7 @@ public void SetMembersOfRelationshipsObject(OpenApiSchema fullSchemaForRelations
     {
         ArgumentGuard.NotNull(fullSchemaForRelationshipsObject);
 
-        foreach ((string fieldName, OpenApiSchema resourceFieldSchema) in _schemasForResourceFields)
+        foreach (string fieldName in _schemasForResourceFields.Keys)
         {
             RelationshipAttribute? matchingRelationship = _resourceTypeInfo.ResourceType.FindRelationshipByPublicName(fieldName);
 
@@ -162,10 +162,6 @@ public void SetMembersOfRelationshipsObject(OpenApiSchema fullSchemaForRelations
             {
                 EnsureResourceIdentifierObjectSchemaExists(matchingRelationship);
                 AddRelationshipSchemaToResourceObject(matchingRelationship, fullSchemaForRelationshipsObject);
-
-                // This currently has no effect because $ref cannot be combined with other elements in OAS 3.0.
-                // This can be worked around by using the allOf operator. See https://github.com/OAI/OpenAPI-Specification/issues/1514.
-                resourceFieldSchema.Description = _resourceObjectDocumentationReader.GetDocumentationForRelationship(matchingRelationship);
             }
         }
     }
@@ -209,7 +205,8 @@ private void AddRelationshipSchemaToResourceObject(RelationshipAttribute relatio
             AllOf = new List<OpenApiSchema>
             {
                 referenceSchemaForRelationship
-            }
+            },
+            Description = _resourceObjectDocumentationReader.GetDocumentationForRelationship(relationship)
         };
 
         fullSchemaForRelationshipsObject.Properties.Add(relationship.PublicName, extendedReferenceSchemaForRelationship);
diff --git a/test/OpenApiTests/DocComments/DocCommentsTests.cs b/test/OpenApiTests/DocComments/DocCommentsTests.cs
index cf14cf66fa..6d7962e47a 100644
--- a/test/OpenApiTests/DocComments/DocCommentsTests.cs
+++ b/test/OpenApiTests/DocComments/DocCommentsTests.cs
@@ -449,7 +449,7 @@ public async Task Resource_types_are_documented()
     }
 
     [Fact]
-    public async Task Resource_attributes_are_documented()
+    public async Task Attributes_are_documented()
     {
         // Act
         JsonElement document = await _testContext.GetSwaggerDocumentAsync();
@@ -465,9 +465,60 @@ public async Task Resource_attributes_are_documented()
             schemasElement.Should().HaveProperty("skyscraperAttributesInPostRequest.properties.heightInMeters.description", "The height of this building, in meters.");
             schemasElement.Should().HaveProperty("skyscraperAttributesInResponse.properties.heightInMeters.description", "The height of this building, in meters.");
 
-            schemasElement.Should().HaveProperty("spaceAttributesInPatchRequest.properties.floorNumber.description", "The floor number on which this space resides.");
-            schemasElement.Should().HaveProperty("spaceAttributesInPostRequest.properties.floorNumber.description", "The floor number on which this space resides.");
-            schemasElement.Should().HaveProperty("spaceAttributesInResponse.properties.floorNumber.description", "The floor number on which this space resides.");
+            schemasElement.Should().ContainPath("spaceAttributesInPatchRequest.properties").With(propertiesElement =>
+            {
+                propertiesElement.Should().HaveProperty("floorNumber.description", "The floor number on which this space resides.");
+                propertiesElement.Should().HaveProperty("kind.description", "The kind of this space.");
+            });
+
+            schemasElement.Should().ContainPath("spaceAttributesInPostRequest.properties").With(propertiesElement =>
+            {
+                propertiesElement.Should().HaveProperty("floorNumber.description", "The floor number on which this space resides.");
+                propertiesElement.Should().HaveProperty("kind.description", "The kind of this space.");
+            });
+
+            schemasElement.Should().ContainPath("spaceAttributesInResponse.properties").With(propertiesElement =>
+            {
+                propertiesElement.Should().HaveProperty("floorNumber.description", "The floor number on which this space resides.");
+                propertiesElement.Should().HaveProperty("kind.description", "The kind of this space.");
+            });
+        });
+    }
+
+    [Fact]
+    public async Task Relationships_are_documented()
+    {
+        // Act
+        JsonElement document = await _testContext.GetSwaggerDocumentAsync();
+
+        // Assert
+        document.Should().ContainPath("components.schemas").With(schemasElement =>
+        {
+            schemasElement.Should().HaveProperty("elevatorRelationshipsInPatchRequest.properties.existsIn.description", "The skyscraper this elevator exists in.");
+            schemasElement.Should().HaveProperty("elevatorRelationshipsInPostRequest.properties.existsIn.description", "The skyscraper this elevator exists in.");
+            schemasElement.Should().HaveProperty("elevatorRelationshipsInResponse.properties.existsIn.description", "The skyscraper this elevator exists in.");
+
+            schemasElement.Should().ContainPath("skyscraperRelationshipsInPatchRequest.properties").With(propertiesElement =>
+            {
+                propertiesElement.Should().HaveProperty("elevator.description", "An optional elevator within this building, providing access to spaces.");
+                propertiesElement.Should().HaveProperty("spaces.description", "The spaces within this building.");
+            });
+
+            schemasElement.Should().ContainPath("skyscraperRelationshipsInPostRequest.properties").With(propertiesElement =>
+            {
+                propertiesElement.Should().HaveProperty("elevator.description", "An optional elevator within this building, providing access to spaces.");
+                propertiesElement.Should().HaveProperty("spaces.description", "The spaces within this building.");
+            });
+
+            schemasElement.Should().ContainPath("skyscraperRelationshipsInResponse.properties").With(propertiesElement =>
+            {
+                propertiesElement.Should().HaveProperty("elevator.description", "An optional elevator within this building, providing access to spaces.");
+                propertiesElement.Should().HaveProperty("spaces.description", "The spaces within this building.");
+            });
+
+            schemasElement.Should().HaveProperty("spaceRelationshipsInPatchRequest.properties.existsIn.description", "The skyscraper this space exists in.");
+            schemasElement.Should().HaveProperty("spaceRelationshipsInPostRequest.properties.existsIn.description", "The skyscraper this space exists in.");
+            schemasElement.Should().HaveProperty("spaceRelationshipsInResponse.properties.existsIn.description", "The skyscraper this space exists in.");
         });
     }