feat(metadata): allow stringable objects in descriptions

src/Metadata/ApiProperty.php

@@ -57,7 +57,7 @@ final class ApiProperty
      * @param Type|null                                                                                                                                   $nativeType              The internal PHP type
      */
     public function __construct(
-        private ?string $description = null,
+        private string|\Stringable|null $description = null,
         private ?bool $readable = null,
         private ?bool $writable = null,
         private ?bool $readableLink = null,
@@ -256,10 +256,10 @@ public function withProperty(string $property): static
 
     public function getDescription(): ?string
     {
-        return $this->description;
+        return $this->description instanceof \Stringable ? (string) $this->description : $this->description;
     }
 
-    public function withDescription(string $description): static
+    public function withDescription(string|\Stringable $description): static
     {
         $self = clone $this;
         $self->description = $description;

src/Metadata/ApiResource.php

@@ -67,7 +67,7 @@ public function __construct(
         /**
          * A description for this resource that will show on documentations.
          */
-        protected ?string $description = null,
+        protected string|\Stringable|null $description = null,
 
         /**
          * The RDF types of this resource.

src/Metadata/Delete.php

@@ -64,7 +64,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/Error.php

@@ -64,7 +64,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/ErrorResource.php

@@ -22,7 +22,7 @@ class ErrorResource extends ApiResource
     public function __construct(
         ?string $uriTemplate = null,
         ?string $shortName = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         array|string|null $types = null,
         $operations = null,
         array|string|null $formats = null,

src/Metadata/Get.php

@@ -64,7 +64,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/GetCollection.php

@@ -64,7 +64,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/GraphQl/Operation.php

@@ -57,7 +57,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/GraphQl/Query.php

@@ -40,7 +40,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/GraphQl/QueryCollection.php

@@ -41,7 +41,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/GraphQl/Subscription.php

@@ -40,7 +40,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/HttpOperation.php

@@ -185,7 +185,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/Link.php

@@ -40,7 +40,7 @@ public function __construct(
         mixed $filter = null,
         ?string $property = null,
         ?array $properties = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?bool $required = null,
         array $extraProperties = [],
 

src/Metadata/McpResource.php

@@ -28,7 +28,7 @@ final class McpResource extends HttpOperation
     /**
      * @param string                                         $uri               The specific URI identifying this resource instance. Must be unique within the server.
      * @param ?string                                        $name              A human-readable name for this resource. If null, a default might be generated from the method name.
-     * @param ?string                                        $description       An optional description of the resource. Defaults to class DocBlock summary.
+     * @param string|\Stringable|null                        $description       An optional description of the resource. Defaults to class DocBlock summary.
      * @param bool|null                                      $structuredContent Whether to include structured content in the response (defaults to true)
      * @param ?string                                        $mimeType          the MIME type, if known and constant for this resource
      * @param ?int                                           $size              the size in bytes, if known and constant
@@ -94,7 +94,7 @@ final class McpResource extends HttpOperation
     public function __construct(
         protected string $uri,
         ?string $name = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         protected ?bool $structuredContent = null,
         protected ?string $mimeType = null,
         protected ?int $size = null,

src/Metadata/McpTool.php

@@ -28,7 +28,7 @@ class McpTool extends HttpOperation
     /**
      * @param string|null                                    $name              The name of the tool (defaults to the method name)
      * @param string|null                                    $title             Optional human-readable title for display in UI
-     * @param string|null                                    $description       The description of the tool (defaults to the DocBlock/inferred)
+     * @param string|\Stringable|null                        $description       The description of the tool (defaults to the DocBlock/inferred)
      * @param bool|null                                      $structuredContent Whether to include structured content in the response (defaults to true)
      * @param mixed|null                                     $annotations       Optional annotations describing tool behavior
      * @param array|null                                     $icons             Optional list of icon URLs representing the tool
@@ -92,7 +92,7 @@ class McpTool extends HttpOperation
     public function __construct(
         ?string $name = null,
         protected ?string $title = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         protected ?bool $structuredContent = null,
         protected mixed $annotations = null,
         protected ?array $icons = null,

src/Metadata/Metadata.php

@@ -39,7 +39,7 @@ abstract class Metadata
     public function __construct(
         protected ?string $shortName = null,
         protected ?string $class = null,
-        protected ?string $description = null,
+        protected string|\Stringable|null $description = null,
         protected ?int $urlGenerationStrategy = null,
         protected ?string $deprecationReason = null,
         protected ?array $normalizationContext = null,
@@ -138,10 +138,10 @@ public function withClass(string $class): static
 
     public function getDescription(): ?string
     {
-        return $this->description;
+        return $this->description instanceof \Stringable ? (string) $this->description : $this->description;
     }
 
-    public function withDescription(?string $description = null): static
+    public function withDescription(string|\Stringable|null $description = null): static
     {
         $self = clone $this;
         $self->description = $description;

src/Metadata/NotExposed.php

@@ -77,7 +77,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/Operation.php

@@ -608,7 +608,7 @@ public function __construct(
          */
         protected ?array $paginationViaCursor = null,
         protected ?array $order = null,
-        protected ?string $description = null,
+        protected string|\Stringable|null $description = null,
         protected ?array $normalizationContext = null,
         protected ?array $denormalizationContext = null,
         protected ?bool $collectDenormalizationErrors = null,

src/Metadata/Parameter.php

@@ -54,7 +54,7 @@ public function __construct(
         protected mixed $provider = null,
         protected mixed $filter = null,
         protected ?string $property = null,
-        protected ?string $description = null,
+        protected string|\Stringable|null $description = null,
         protected ?array $properties = null,
         protected ?bool $required = null,
         protected ?int $priority = null,
@@ -115,7 +115,7 @@ public function getFilter(): mixed
 
     public function getDescription(): ?string
     {
-        return $this->description;
+        return $this->description instanceof \Stringable ? (string) $this->description : $this->description;
     }
 
     public function getRequired(): ?bool
@@ -258,7 +258,7 @@ public function withProperty(string $property): static
         return $self;
     }
 
-    public function withDescription(string $description): static
+    public function withDescription(string|\Stringable $description): static
     {
         $self = clone $this;
         $self->description = $description;

src/Metadata/Patch.php

@@ -64,7 +64,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/Post.php

@@ -64,7 +64,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/Put.php

@@ -64,7 +64,7 @@ public function __construct(
         ?bool $paginationFetchJoinCollection = null,
         ?bool $paginationUseOutputWalkers = null,
         ?array $order = null,
-        ?string $description = null,
+        string|\Stringable|null $description = null,
         ?array $normalizationContext = null,
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,

src/Metadata/Tests/Resource/StringableDescriptionParameterTest.php

@@ -0,0 +1,88 @@
+<?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\Metadata\Tests\Resource;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Error;
+use ApiPlatform\Metadata\ErrorResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\GraphQl\Mutation;
+use ApiPlatform\Metadata\GraphQl\Query;
+use ApiPlatform\Metadata\GraphQl\QueryCollection;
+use ApiPlatform\Metadata\GraphQl\Subscription;
+use ApiPlatform\Metadata\Metadata;
+use ApiPlatform\Metadata\NotExposed;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\Post;
+use ApiPlatform\Metadata\Put;
+use ApiPlatform\Metadata\Tests\Fixtures\Metadata\RestfulApi;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class StringableDescriptionParameterTest extends TestCase
+{
+    #[DataProvider('metadataProvider')]
+    public function testOnMetadata(Metadata $metadata): void
+    {
+        $this->assertSame($metadata->getDescription(), 'stringable_description');
+    }
+
+    public static function metadataProvider(): \Generator
+    {
+        $stringableDescription = new class implements \Stringable {
+            public function __toString(): string
+            {
+                return 'stringable_description';
+            }
+        };
+        $args = [
+            'description' => $stringableDescription,
+        ];
+
+        yield [new Get(...$args)];
+        yield [new GetCollection(...$args)];
+        yield [new Post(...$args)];
+        yield [new Put(...$args)];
+        yield [new Patch(...$args)];
+        yield [new Delete(...$args)];
+        yield [new Error(...$args)];
+        yield [new NotExposed(...$args)];
+        yield [new Query(...$args)];
+        yield [new QueryCollection(...$args)];
+        yield [new Mutation(...$args)];
+        yield [new Subscription(...$args)];
+        yield [new ApiResource(...$args)];
+        yield [new ErrorResource(...$args)];
+        yield [new RestfulApi(...$args)];
+    }
+
+    public function testOnApiProperty(): void
+    {
+        $stringableDescription = new class implements \Stringable {
+            public function __toString(): string
+            {
+                return 'stringable_description';
+            }
+        };
+
+        $metadata = new ApiProperty(
+            description: $stringableDescription,
+        );
+
+        $this->assertSame($metadata->getDescription(), 'stringable_description');
+    }
+}