fix(jsonschema): keep description and externalDocs on nested resources

src/JsonSchema/ResourceMetadataTrait.php

@@ -51,7 +51,9 @@ private function findOperation(string $className, string $type, ?Operation $oper
             }
             $forceSubschema = $serializerContext[SchemaFactory::FORCE_SUBSCHEMA] ?? false;
             if ($operation->getShortName() === $this->getShortClassName($className) && $forceSubschema) {
-                $operation = new HttpOperation();
+                $operation = (new HttpOperation())
+                    ->withDescription($operation->getDescription())
+                    ->withTypes($operation instanceof HttpOperation ? $operation->getTypes() : null);
             }
 
             $operation = $this->findOperationForType($resourceMetadataCollection, $type, $operation, $forceSubschema ? null : $format);

tests/Fixtures/TestBundle/ApiResource/JsonSchemaNestedOutputDto/DocumentedRelated.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto;
+
+use ApiPlatform\Metadata\ApiResource;
+
+#[ApiResource(description: 'A schema type', types: ['https://schema.org/Thing'], operations: [])]
+class DocumentedRelated
+{
+    public string $name = '';
+}

tests/Fixtures/TestBundle/ApiResource/JsonSchemaNestedOutputDto/OwnerOfDocumentedRelated.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\Get;
+
+#[Get]
+class OwnerOfDocumentedRelated
+{
+    #[ApiProperty(identifier: true)]
+    public int $id = 0;
+    #[ApiProperty(readableLink: true)]
+    public DocumentedRelated $related;
+}

tests/Functional/JsonSchema/JsonSchemaNestedOutputDtoTest.php

@@ -20,8 +20,10 @@
 use ApiPlatform\Test\ApiTestCase;
 use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\AliasedRelatedWithOutput;
 use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\DeprecatedRelated;
+use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\DocumentedRelated;
 use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\OwnerOfAliasedRelated;
 use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\OwnerOfDeprecatedRelated;
+use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\OwnerOfDocumentedRelated;
 use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\OwnerOfRelatedWithOutput;
 use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\JsonSchemaNestedOutputDto\RelatedWithOutput;
 use ApiPlatform\Tests\SetupClassResourcesTrait;
@@ -52,6 +54,8 @@ public static function getResources(): array
             AliasedRelatedWithOutput::class,
             OwnerOfDeprecatedRelated::class,
             DeprecatedRelated::class,
+            OwnerOfDocumentedRelated::class,
+            DocumentedRelated::class,
         ];
     }
 
@@ -76,6 +80,24 @@ public function testJsonLdNestedRelatedIsNotDeprecated(): void
         $this->assertArrayNotHasKey('deprecated', $this->objectPart($this->relatedDefinition($schema)));
     }
 
+    public function testJsonLdNestedRelatedKeepsDescriptionAndExternalDocs(): void
+    {
+        $schema = $this->schemaFactory->buildSchema(OwnerOfDocumentedRelated::class, 'jsonld');
+        $related = $this->relatedDefinition($schema);
+
+        $this->assertSame('A schema type', $related['description'] ?? null);
+        $this->assertSame(['url' => 'https://schema.org/Thing'], $this->objectPart($related)['externalDocs'] ?? null);
+    }
+
+    public function testJsonNestedRelatedKeepsDescriptionAndExternalDocs(): void
+    {
+        $schema = $this->schemaFactory->buildSchema(OwnerOfDocumentedRelated::class, 'json');
+        $related = $this->relatedDefinition($schema);
+
+        $this->assertSame('A schema type', $related['description'] ?? null);
+        $this->assertSame(['url' => 'https://schema.org/Thing'], $this->objectPart($related)['externalDocs'] ?? null);
+    }
+
     public function testExplicitOperationWithForceSubschemaDescribesOutputDto(): void
     {
         /** @var ResourceMetadataCollectionFactoryInterface $resourceMetadataCollectionFactory */