Fix generated documentation on relationships

Author: bkoelman

src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceFieldObjectSchemaBuilder.cs

@@ -154,18 +154,14 @@ 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);
 
             if (matchingRelationship != null)
             {
                 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);

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();
@@ -471,6 +471,43 @@ public async Task Resource_attributes_are_documented()
         });
     }
 
+    [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.");
+        });
+    }
+
     [Fact]
     public async Task Enums_are_documented()
     {