feat(openapi): add error resources schemes

src/Metadata/Delete.php

@@ -49,6 +49,7 @@ public function __construct(
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -127,6 +128,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/Metadata/Error.php

@@ -49,6 +49,7 @@ public function __construct(
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -125,6 +126,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/Metadata/Get.php

@@ -49,6 +49,7 @@ public function __construct(
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -126,6 +127,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/Metadata/GetCollection.php

@@ -49,6 +49,7 @@ public function __construct(
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -127,6 +128,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/Metadata/HttpOperation.php

@@ -13,6 +13,7 @@
 
 namespace ApiPlatform\Metadata;
 
+use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;
 use ApiPlatform\OpenApi\Attributes\Webhook;
 use ApiPlatform\OpenApi\Model\Operation as OpenApiOperation;
 use ApiPlatform\State\OptionsInterface;
@@ -73,11 +74,12 @@ class HttpOperation extends Operation
      *     class?: string|null,
      *     name?: string,
      * }|string|false|null $output {@see https://api-platform.com/docs/core/dto/#specifying-an-input-or-an-output-data-representation}
-     * @param string|array|bool|null $mercure   {@see https://api-platform.com/docs/core/mercure}
-     * @param string|bool|null       $messenger {@see https://api-platform.com/docs/core/messenger/#dispatching-a-resource-through-the-message-bus}
-     * @param string|callable|null   $provider  {@see https://api-platform.com/docs/core/state-providers/#state-providers}
-     * @param string|callable|null   $processor {@see https://api-platform.com/docs/core/state-processors/#state-processors}
-     * @param WebLink[]|null         $links
+     * @param string|array|bool|null                              $mercure   {@see https://api-platform.com/docs/core/mercure}
+     * @param string|bool|null                                    $messenger {@see https://api-platform.com/docs/core/messenger/#dispatching-a-resource-through-the-message-bus}
+     * @param string|callable|null                                $provider  {@see https://api-platform.com/docs/core/state-providers/#state-providers}
+     * @param string|callable|null                                $processor {@see https://api-platform.com/docs/core/state-processors/#state-processors}
+     * @param WebLink[]|null                                      $links
+     * @param array<class-string<ProblemExceptionInterface>>|null $errors
      */
     public function __construct(
         protected string $method = 'GET',
@@ -154,6 +156,7 @@ public function __construct(
         protected bool|OpenApiOperation|Webhook|null $openapi = null,
         protected ?array $exceptionToStatus = null,
         protected ?array $links = null,
+        protected ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -623,4 +626,20 @@ public function withLinks(array $links): self
 
         return $self;
     }
+
+    public function getErrors(): ?array
+    {
+        return $this->errors;
+    }
+
+    /**
+     * @param class-string<ProblemExceptionInterface>[] $errors
+     */
+    public function withErrors(array $errors): self
+    {
+        $self = clone $this;
+        $self->errors = $errors;
+
+        return $self;
+    }
 }

src/Metadata/NotExposed.php

@@ -62,6 +62,7 @@ public function __construct(
 
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -139,6 +140,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/Metadata/Patch.php

@@ -49,6 +49,7 @@ public function __construct(
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -127,6 +128,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/Metadata/Post.php

@@ -49,6 +49,7 @@ public function __construct(
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -128,6 +129,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/Metadata/Put.php

@@ -49,6 +49,7 @@ public function __construct(
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
         ?array $links = null,
+        ?array $errors = null,
 
         ?string $shortName = null,
         ?string $class = null,
@@ -128,6 +129,7 @@ public function __construct(
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
             links: $links,
+            errors: $errors,
             shortName: $shortName,
             class: $class,
             paginationEnabled: $paginationEnabled,

src/OpenApi/Factory/OpenApiFactory.php

@@ -20,6 +20,11 @@
 use ApiPlatform\JsonSchema\TypeFactoryInterface;
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\CollectionOperationInterface;
+use ApiPlatform\Metadata\Error;
+use ApiPlatform\Metadata\Exception\OperationNotFoundException;
+use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;
+use ApiPlatform\Metadata\Exception\ResourceClassNotFoundException;
+use ApiPlatform\Metadata\Exception\RuntimeException;
 use ApiPlatform\Metadata\HeaderParameterInterface;
 use ApiPlatform\Metadata\HttpOperation;
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
@@ -38,6 +43,7 @@
 use ApiPlatform\OpenApi\Model\MediaType;
 use ApiPlatform\OpenApi\Model\OAuthFlow;
 use ApiPlatform\OpenApi\Model\OAuthFlows;
+use ApiPlatform\OpenApi\Model\Operation;
 use ApiPlatform\OpenApi\Model\Parameter;
 use ApiPlatform\OpenApi\Model\PathItem;
 use ApiPlatform\OpenApi\Model\Paths;
@@ -75,8 +81,19 @@ final class OpenApiFactory implements OpenApiFactoryInterface
      */
     public const OPENAPI_DEFINITION_NAME = 'openapi_definition_name';
 
-    public function __construct(private readonly ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory, private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory, private readonly PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory, private readonly SchemaFactoryInterface $jsonSchemaFactory, ?TypeFactoryInterface $jsonSchemaTypeFactory, ContainerInterface $filterLocator, private readonly array $formats = [], ?Options $openApiOptions = null, ?PaginationOptions $paginationOptions = null, private readonly ?RouterInterface $router = null)
-    {
+    public function __construct(
+        private readonly ResourceNameCollectionFactoryInterface $resourceNameCollectionFactory,
+        private readonly ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory,
+        private readonly PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory,
+        private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory,
+        private readonly SchemaFactoryInterface $jsonSchemaFactory,
+        ?TypeFactoryInterface $jsonSchemaTypeFactory,
+        ContainerInterface $filterLocator,
+        private readonly array $formats = [],
+        ?Options $openApiOptions = null,
+        ?PaginationOptions $paginationOptions = null,
+        private readonly ?RouterInterface $router = null,
+    ) {
         $this->filterLocator = $filterLocator;
         $this->openApiOptions = $openApiOptions ?: new Options('API Platform');
         $this->paginationOptions = $paginationOptions ?: new PaginationOptions();
@@ -181,15 +198,15 @@ private function collectPaths(ApiResource $resource, ResourceMetadataCollection
 
             if ($openapiAttribute instanceof Webhook) {
                 $pathItem = $openapiAttribute->getPathItem() ?: new PathItem();
-                $openapiOperation = $pathItem->{'get'.ucfirst(strtolower($method))}() ?: new Model\Operation();
+                $openapiOperation = $pathItem->{'get'.ucfirst(strtolower($method))}() ?: new Operation();
             } elseif (!\is_object($openapiAttribute)) {
-                $openapiOperation = new Model\Operation();
+                $openapiOperation = new Operation();
             } else {
                 $openapiOperation = $openapiAttribute;
             }
 
             // Complete with defaults
-            $openapiOperation = new Model\Operation(
+            $openapiOperation = new Operation(
                 operationId: null !== $openapiOperation->getOperationId() ? $openapiOperation->getOperationId() : $this->normalizeOperationName($operationName),
                 tags: null !== $openapiOperation->getTags() ? $openapiOperation->getTags() : [$operation->getShortName() ?: $resourceShortName],
                 responses: null !== $openapiOperation->getResponses() ? $openapiOperation->getResponses() : [],
@@ -339,6 +356,10 @@ private function collectPaths(ApiResource $resource, ResourceMetadataCollection
 
             $existingResponses = $openapiOperation?->getResponses() ?: [];
             $overrideResponses = $operation->getExtraProperties()[self::OVERRIDE_OPENAPI_RESPONSES] ?? $this->openApiOptions->getOverrideResponses();
+            if ($operation instanceof HttpOperation && null !== ($errors = $operation->getErrors())) {
+                $openapiOperation = $this->addOperationErrors($openapiOperation, $errors, $responseMimeTypes, $resourceMetadataCollection, $schema, $schemas);
+            }
+
             if ($overrideResponses || !$existingResponses) {
                 // Create responses
                 switch ($method) {
@@ -433,7 +454,7 @@ private function collectPaths(ApiResource $resource, ResourceMetadataCollection
                     '3.1',
                     'The "openapiContext" option is deprecated, use "openapi" instead.'
                 );
-                $allowedProperties = array_map(fn (\ReflectionProperty $reflProperty): string => $reflProperty->getName(), (new \ReflectionClass(Model\Operation::class))->getProperties());
+                $allowedProperties = array_map(fn (\ReflectionProperty $reflProperty): string => $reflProperty->getName(), (new \ReflectionClass(Operation::class))->getProperties());
                 foreach ($operation->getOpenapiContext() as $key => $value) {
                     $value = match ($key) {
                         'externalDocs' => new ExternalDocumentation(description: $value['description'] ?? '', url: $value['url'] ?? ''),
@@ -460,7 +481,7 @@ private function collectPaths(ApiResource $resource, ResourceMetadataCollection
         }
     }
 
-    private function buildOpenApiResponse(array $existingResponses, int|string $status, string $description, ?Model\Operation $openapiOperation = null, ?HttpOperation $operation = null, ?array $responseMimeTypes = null, ?array $operationOutputSchemas = null, ?ResourceMetadataCollection $resourceMetadataCollection = null): Model\Operation
+    private function buildOpenApiResponse(array $existingResponses, int|string $status, string $description, ?Operation $openapiOperation = null, ?HttpOperation $operation = null, ?array $responseMimeTypes = null, ?array $operationOutputSchemas = null, ?ResourceMetadataCollection $resourceMetadataCollection = null): Operation
     {
         if (isset($existingResponses[$status])) {
             return $openapiOperation;
@@ -491,6 +512,9 @@ private function buildContent(array $responseMimeTypes, array $operationSchemas)
         return $content;
     }
 
+    /**
+     * @return array[array<string, string>, array<string, string>]
+     */
     private function getMimeTypes(HttpOperation $operation): array
     {
         $requestFormats = $operation->getInputFormats() ?: [];
@@ -502,6 +526,11 @@ private function getMimeTypes(HttpOperation $operation): array
         return [$requestMimeTypes, $responseMimeTypes];
     }
 
+    /**
+     * @param array<string, string[]> $responseFormats
+     *
+     * @return array<string, string>
+     */
     private function flattenMimeTypes(array $responseFormats): array
     {
         $responseMimeTypes = [];
@@ -803,7 +832,7 @@ private function appendSchemaDefinitions(\ArrayObject $schemas, \ArrayObject $de
     /**
      * @return array{0: int, 1: Parameter}|null
      */
-    private function hasParameter(Model\Operation $operation, Parameter $parameter): ?array
+    private function hasParameter(Operation $operation, Parameter $parameter): ?array
     {
         foreach ($operation->getParameters() as $key => $existingParameter) {
             if ($existingParameter->getName() === $parameter->getName() && $existingParameter->getIn() === $parameter->getIn()) {
@@ -843,4 +872,55 @@ private function mergeParameter(Parameter $actual, Parameter $defined): Paramete
 
         return $actual;
     }
+
+    /**
+     * @param string[]              $errors
+     * @param array<string, string> $responseMimeTypes
+     */
+    private function addOperationErrors(Operation $operation, array $errors, array $responseMimeTypes, ResourceMetadataCollection $resourceMetadataCollection, Schema $schema, \ArrayObject $schemas): Operation
+    {
+        $existingResponses = null;
+        foreach ($errors as $error) {
+            if (!is_a($error, ProblemExceptionInterface::class, true)) {
+                throw new RuntimeException(\sprintf('The error class "%s" does not implement "%s". Did you forget a use statement?', $error, ProblemExceptionInterface::class));
+            }
+
+            $status = null;
+            $description = null;
+
+            try {
+                /** @var ProblemExceptionInterface $exception */
+                $exception = new $error();
+                $status = $exception->getStatus();
+                $description = $exception->getTitle();
+            } catch (\TypeError) {
+            }
+
+            try {
+                $errorOperation = $this->resourceMetadataFactory->create($error)->getOperation();
+                if (!is_a($errorOperation, Error::class)) {
+                    throw new RuntimeException(\sprintf('The error class %s is not an ErrorResource', $error));
+                }
+            } catch (ResourceClassNotFoundException|OperationNotFoundException) {
+                $errorOperation = null;
+            }
+            $status ??= $errorOperation?->getStatus();
+            $description ??= $errorOperation?->getDescription();
+
+            if (!$status) {
+                throw new RuntimeException(\sprintf('The error class %s has no status defined, please either implement ProblemExceptionInterface, or make it an ErrorResource with a status', $error));
+            }
+
+            $operationErrorSchemas = [];
+            foreach ($responseMimeTypes as $operationFormat) {
+                $operationErrorSchema = $this->jsonSchemaFactory->buildSchema($error, $operationFormat, Schema::TYPE_OUTPUT, null, $schema);
+                $operationErrorSchemas[$operationFormat] = $operationErrorSchema;
+                $this->appendSchemaDefinitions($schemas, $operationErrorSchema->getDefinitions());
+            }
+
+            $operation = $this->buildOpenApiResponse($existingResponses ??= $operation->getResponses() ?: [], $status, $description ?? '', $operation, $errorOperation, $responseMimeTypes, $operationErrorSchemas, $resourceMetadataCollection);
+        }
+
+        return $operation;
+    }
 }