feat(openapi): document error outputs using json-schemas

api-platform · Jan 27, 2025 · 0d1473f · 0d1473f
1 parent d676103
commit 0d1473f
Show file tree

Hide file tree

Showing 16 changed files with 624 additions and 264 deletions.
diff --git a/src/JsonApi/JsonSchema/SchemaFactory.php b/src/JsonApi/JsonSchema/SchemaFactory.php
@@ -22,6 +22,7 @@
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\ResourceClassResolverInterface;
+use ApiPlatform\State\ApiResource\Error;
 
 /**
  * Decorator factory which adds JSON:API properties to the JSON Schema document.
@@ -31,6 +32,14 @@
 final class SchemaFactory implements SchemaFactoryInterface, SchemaFactoryAwareInterface
 {
     use ResourceMetadataTrait;
+
+    /**
+     * As JSON:API recommends using [includes](https://jsonapi.org/format/#fetching-includes) instead of groups
+     * this flag allows to force using groups to generate the JSON:API JSONSchema. Defaults to true, use it in
+     * a serializer context.
+     */
+    public const DISABLE_JSON_SCHEMA_SERIALIZER_GROUPS = 'disable_json_schema_serializer_groups';
+
     private const LINKS_PROPS = [
         'type' => 'object',
         'properties' => [
@@ -124,14 +133,27 @@ public function buildSchema(string $className, string $format = 'jsonapi', strin
         }
         // We don't use the serializer context here as JSON:API doesn't leverage serializer groups for related resources.
         // That is done by query parameter. @see https://jsonapi.org/format/#fetching-includes
-        $schema = $this->schemaFactory->buildSchema($className, $format, $type, $operation, $schema, [], $forceCollection);
+        $serializerContext ??= $this->getSerializerContext($operation ?? $this->findOperation($className, $type, $operation, $serializerContext, $format), $type);
+        $jsonApiSerializerContext = !($serializerContext[self::DISABLE_JSON_SCHEMA_SERIALIZER_GROUPS] ?? true) ? $serializerContext : [];
+        $schema = $this->schemaFactory->buildSchema($className, $format, $type, $operation, $schema, $jsonApiSerializerContext, $forceCollection);
 
         if (($key = $schema->getRootDefinitionKey()) || ($key = $schema->getItemsDefinitionKey())) {
             $definitions = $schema->getDefinitions();
             $properties = $definitions[$key]['properties'] ?? [];
 
+            if (Error::class === $className && !isset($properties['errors'])) {
+                $definitions[$key]['properties'] = [
+                    'errors' => [
+                        'type' => 'object',
+                        'properties' => $properties,
+                    ],
+                ];
+
+                return $schema;
+            }
+
             // Prevent reapplying
-            if (isset($properties['id'], $properties['type']) || isset($properties['data'])) {
+            if (isset($properties['id'], $properties['type']) || isset($properties['data']) || isset($properties['errors'])) {
                 return $schema;
             }
 

diff --git a/src/JsonSchema/ResourceMetadataTrait.php b/src/JsonSchema/ResourceMetadataTrait.php
@@ -36,7 +36,7 @@ private function findOutputClass(string $className, string $type, Operation $ope
         return $forceSubschema ? ($inputOrOutput['class'] ?? $inputOrOutput->class ?? $operation->getClass()) : ($inputOrOutput['class'] ?? $inputOrOutput->class ?? null);
     }
 
-    private function findOperation(string $className, string $type, ?Operation $operation, ?array $serializerContext): Operation
+    private function findOperation(string $className, string $type, ?Operation $operation, ?array $serializerContext, ?string $format = null): Operation
     {
         if (null === $operation) {
             if (null === $this->resourceMetadataFactory) {
@@ -54,7 +54,7 @@ private function findOperation(string $className, string $type, ?Operation $oper
                 $operation = new HttpOperation();
             }
 
-            return $this->findOperationForType($resourceMetadataCollection, $type, $operation);
+            return $this->findOperationForType($resourceMetadataCollection, $type, $operation, $format);
         }
 
         // The best here is to use an Operation when calling `buildSchema`, we try to do a smart guess otherwise
@@ -65,13 +65,13 @@ private function findOperation(string $className, string $type, ?Operation $oper
                 return $resourceMetadataCollection->getOperation($operation->getName());
             }
 
-            return $this->findOperationForType($resourceMetadataCollection, $type, $operation);
+            return $this->findOperationForType($resourceMetadataCollection, $type, $operation, $format);
         }
 
         return $operation;
     }
 
-    private function findOperationForType(ResourceMetadataCollection $resourceMetadataCollection, string $type, Operation $operation): Operation
+    private function findOperationForType(ResourceMetadataCollection $resourceMetadataCollection, string $type, Operation $operation, ?string $format = null): Operation
     {
         // Find the operation and use the first one that matches criterias
         foreach ($resourceMetadataCollection as $resourceMetadata) {
@@ -85,6 +85,11 @@ private function findOperationForType(ResourceMetadataCollection $resourceMetada
                     $operation = $op;
                     break 2;
                 }
+
+                if ($format && Schema::TYPE_OUTPUT === $type && \array_key_exists($format, $op->getOutputFormats() ?? [])) {
+                    $operation = $op;
+                    break 2;
+                }
             }
         }
 

diff --git a/src/Laravel/Eloquent/Metadata/Factory/Property/EloquentPropertyMetadataFactory.php b/src/Laravel/Eloquent/Metadata/Factory/Property/EloquentPropertyMetadataFactory.php
@@ -46,6 +46,10 @@ public function __construct(
      */
     public function create(string $resourceClass, string $property, array $options = []): ApiProperty
     {
+        if (!is_a($resourceClass, Model::class, true)) {
+            return $this->decorated?->create($resourceClass, $property, $options) ?? new ApiProperty();
+        }
+
         try {
             $refl = new \ReflectionClass($resourceClass);
             $model = $refl->newInstanceWithoutConstructor();

diff --git a/src/Metadata/ApiProperty.php b/src/Metadata/ApiProperty.php
@@ -231,7 +231,7 @@ public function getProperty(): ?string
         return $this->property;
     }
 
-    public function withProperty(string $property): self
+    public function withProperty(string $property): static
     {
         $self = clone $this;
         $self->property = $property;
@@ -244,7 +244,7 @@ public function getDescription(): ?string
         return $this->description;
     }
 
-    public function withDescription(string $description): self
+    public function withDescription(string $description): static
     {
         $self = clone $this;
         $self->description = $description;
@@ -257,7 +257,7 @@ public function isReadable(): ?bool
         return $this->readable;
     }
 
-    public function withReadable(bool $readable): self
+    public function withReadable(bool $readable): static
     {
         $self = clone $this;
         $self->readable = $readable;
@@ -270,7 +270,7 @@ public function isWritable(): ?bool
         return $this->writable;
     }
 
-    public function withWritable(bool $writable): self
+    public function withWritable(bool $writable): static
     {
         $self = clone $this;
         $self->writable = $writable;
@@ -283,7 +283,7 @@ public function isReadableLink(): ?bool
         return $this->readableLink;
     }
 
-    public function withReadableLink(bool $readableLink): self
+    public function withReadableLink(bool $readableLink): static
     {
         $self = clone $this;
         $self->readableLink = $readableLink;
@@ -296,7 +296,7 @@ public function isWritableLink(): ?bool
         return $this->writableLink;
     }
 
-    public function withWritableLink(bool $writableLink): self
+    public function withWritableLink(bool $writableLink): static
     {
         $self = clone $this;
         $self->writableLink = $writableLink;
@@ -309,7 +309,7 @@ public function isRequired(): ?bool
         return $this->required;
     }
 
-    public function withRequired(bool $required): self
+    public function withRequired(bool $required): static
     {
         $self = clone $this;
         $self->required = $required;
@@ -322,7 +322,7 @@ public function isIdentifier(): ?bool
         return $this->identifier;
     }
 
-    public function withIdentifier(bool $identifier): self
+    public function withIdentifier(bool $identifier): static
     {
         $self = clone $this;
         $self->identifier = $identifier;
@@ -335,7 +335,7 @@ public function getDefault()
         return $this->default;
     }
 
-    public function withDefault($default): self
+    public function withDefault($default): static
     {
         $self = clone $this;
         $self->default = $default;
@@ -348,7 +348,7 @@ public function getExample(): mixed
         return $this->example;
     }
 
-    public function withExample(mixed $example): self
+    public function withExample(mixed $example): static
     {
         $self = clone $this;
         $self->example = $example;
@@ -361,7 +361,7 @@ public function getDeprecationReason(): ?string
         return $this->deprecationReason;
     }
 
-    public function withDeprecationReason($deprecationReason): self
+    public function withDeprecationReason($deprecationReason): static
     {
         $self = clone $this;
         $self->deprecationReason = $deprecationReason;
@@ -374,7 +374,7 @@ public function isFetchable(): ?bool
         return $this->fetchable;
     }
 
-    public function withFetchable($fetchable): self
+    public function withFetchable($fetchable): static
     {
         $self = clone $this;
         $self->fetchable = $fetchable;
@@ -387,7 +387,7 @@ public function getFetchEager(): ?bool
         return $this->fetchEager;
     }
 
-    public function withFetchEager($fetchEager): self
+    public function withFetchEager($fetchEager): static
     {
         $self = clone $this;
         $self->fetchEager = $fetchEager;
@@ -400,7 +400,7 @@ public function getJsonldContext(): ?array
         return $this->jsonldContext;
     }
 
-    public function withJsonldContext($jsonldContext): self
+    public function withJsonldContext($jsonldContext): static
     {
         $self = clone $this;
         $self->jsonldContext = $jsonldContext;
@@ -413,7 +413,7 @@ public function getOpenapiContext(): ?array
         return $this->openapiContext;
     }
 
-    public function withOpenapiContext($openapiContext): self
+    public function withOpenapiContext($openapiContext): static
     {
         $self = clone $this;
         $self->openapiContext = $openapiContext;
@@ -426,7 +426,7 @@ public function getJsonSchemaContext(): ?array
         return $this->jsonSchemaContext;
     }
 
-    public function withJsonSchemaContext($jsonSchemaContext): self
+    public function withJsonSchemaContext($jsonSchemaContext): static
     {
         $self = clone $this;
         $self->jsonSchemaContext = $jsonSchemaContext;
@@ -439,7 +439,7 @@ public function getPush(): ?bool
         return $this->push;
     }
 
-    public function withPush($push): self
+    public function withPush($push): static
     {
         $self = clone $this;
         $self->push = $push;
@@ -452,7 +452,7 @@ public function getSecurity(): ?string
         return $this->security instanceof \Stringable ? (string) $this->security : $this->security;
     }
 
-    public function withSecurity($security): self
+    public function withSecurity($security): static
     {
         $self = clone $this;
         $self->security = $security;
@@ -465,7 +465,7 @@ public function getSecurityPostDenormalize(): ?string
         return $this->securityPostDenormalize instanceof \Stringable ? (string) $this->securityPostDenormalize : $this->securityPostDenormalize;
     }
 
-    public function withSecurityPostDenormalize($securityPostDenormalize): self
+    public function withSecurityPostDenormalize($securityPostDenormalize): static
     {
         $self = clone $this;
         $self->securityPostDenormalize = $securityPostDenormalize;
@@ -481,7 +481,7 @@ public function getTypes(): ?array
     /**
      * @param string[]|string $types
      */
-    public function withTypes(array|string $types = []): self
+    public function withTypes(array|string $types = []): static
     {
         $self = clone $this;
         $self->types = (array) $types;
@@ -500,7 +500,7 @@ public function getBuiltinTypes(): ?array
     /**
      * @param Type[] $builtinTypes
      */
-    public function withBuiltinTypes(array $builtinTypes = []): self
+    public function withBuiltinTypes(array $builtinTypes = []): static
     {
         $self = clone $this;
         $self->builtinTypes = $builtinTypes;
@@ -513,15 +513,15 @@ public function getSchema(): ?array
         return $this->schema;
     }
 
-    public function withSchema(array $schema = []): self
+    public function withSchema(array $schema = []): static
     {
         $self = clone $this;
         $self->schema = $schema;
 
         return $self;
     }
 
-    public function withInitializable(bool $initializable): self
+    public function withInitializable(?bool $initializable): static
     {
         $self = clone $this;
         $self->initializable = $initializable;
@@ -539,7 +539,7 @@ public function getExtraProperties(): ?array
         return $this->extraProperties;
     }
 
-    public function withExtraProperties(array $extraProperties = []): self
+    public function withExtraProperties(array $extraProperties = []): static
     {
         $self = clone $this;
         $self->extraProperties = $extraProperties;
@@ -560,7 +560,7 @@ public function getIris()
      *
      * @param string|string[] $iris
      */
-    public function withIris(string|array $iris): self
+    public function withIris(string|array $iris): static
     {
         $metadata = clone $this;
         $metadata->iris = (array) $iris;
@@ -576,7 +576,7 @@ public function getGenId()
         return $this->genId;
     }
 
-    public function withGenId(bool $genId): self
+    public function withGenId(bool $genId): static
     {
         $metadata = clone $this;
         $metadata->genId = $genId;
@@ -594,7 +594,7 @@ public function getUriTemplate(): ?string
         return $this->uriTemplate;
     }
 
-    public function withUriTemplate(?string $uriTemplate): self
+    public function withUriTemplate(?string $uriTemplate): static
     {
         $metadata = clone $this;
         $metadata->uriTemplate = $uriTemplate;