Fix JSON:API collection included schema

Author: Will-thom

src/JsonApi/JsonSchema/SchemaFactory.php

@@ -259,15 +259,21 @@ public function buildSchema(string $className, string $format = 'jsonapi', strin
         $properties = $this->buildDefinitionPropertiesSchema($key, $className, $format, $type, $operation, $schema, []);
         $properties['data']['properties']['attributes']['$ref'] = $prefix.$key;
 
+        $collectionProperties = [
+            'data' => [
+                'type' => 'array',
+                'items' => $properties['data'],
+            ],
+        ];
+
+        if (isset($properties['included'])) {
+            $collectionProperties['included'] = $properties['included'];
+        }
+
         $schema['description'] = "$definitionName collection.";
         $schema['allOf'] = [
             ['$ref' => $prefix.(false === $operation->getPaginationEnabled() ? self::COLLECTION_BASE_SCHEMA_NAME_NO_PAGINATION : self::COLLECTION_BASE_SCHEMA_NAME)],
-            ['type' => 'object', 'properties' => [
-                'data' => [
-                    'type' => 'array',
-                    'items' => $properties['data'],
-                ],
-            ]],
+            ['type' => 'object', 'properties' => $collectionProperties],
         ];
 
         return $schema;

tests/Functional/OpenApiTest.php

@@ -261,6 +261,24 @@ public function testHasSchemasForMultipleFormats(): void
         ], 'description' => 'A resource used for OpenAPI tests.'], $res['components']['schemas']['Crud.jsonld']);
     }
 
+    public function testJsonApiCollectionSchemaDocumentsIncludedResources(): void
+    {
+        $response = self::createClient()->request('GET', '/docs', [
+            'headers' => ['Accept' => 'application/vnd.openapi+json'],
+        ]);
+
+        $this->assertResponseIsSuccessful();
+        $json = $response->toArray();
+        $schema = $json['paths']['/dummies']['get']['responses']['200']['content']['application/vnd.api+json']['schema'];
+        $properties = $schema['allOf'][1]['properties'];
+
+        $this->assertArrayHasKey('included', $properties);
+        $this->assertSame('array', $properties['included']['type']);
+        $this->assertTrue($properties['included']['readOnly']);
+        $this->assertArrayHasKey('anyOf', $properties['included']['items']);
+        $this->assertNotEmpty($properties['included']['items']['anyOf']);
+    }
+
     public function testRetrieveTheOpenApiDocumentation(): void
     {
         $response = self::createClient()->request('GET', '/docs', ['headers' => ['accept' => 'application/vnd.openapi+json']]);