Merge pull request api-platform#4427 from dunglas/fix/api-property-types

feat(medata): ApiProperty: fix types and improve docs

Author: dunglas

src/Metadata/ApiProperty.php

@@ -83,8 +83,6 @@ final class ApiProperty
     private $securityPostDenormalize;
 
     /**
-     * The related schemas.
-     *
      * @var string[]
      */
     private $types;
@@ -108,20 +106,21 @@ final class ApiProperty
      * @param string                      $description
      * @param bool                        $readable
      * @param bool                        $writable
-     * @param bool                        $readableLink
-     * @param bool                        $writableLink
-     * @param bool                        $required
-     * @param bool                        $identifier
+     * @param bool                        $readableLink            https://api-platform.com/docs/core/serialization/#force-iri-with-relations-of-the-same-type-parentchilds-relations
+     * @param bool                        $writableLink            https://api-platform.com/docs/core/serialization/#force-iri-with-relations-of-the-same-type-parentchilds-relations
+     * @param bool                        $required                https://api-platform.com/docs/admin/validation/#client-side-validation
+     * @param bool                        $identifier              https://api-platform.com/docs/core/identifiers/
      * @param string|int|float|bool|array $default
-     * @param string|int|float|bool|array $example
-     * @param string                      $deprecationReason
+     * @param string|int|float|bool|array $example                 https://api-platform.com/docs/core/openapi/#using-the-openapi-and-swagger-contexts
+     * @param string                      $deprecationReason       https://api-platform.com/docs/core/deprecations/#deprecating-resource-classes-operations-and-properties
      * @param bool                        $fetchable
-     * @param bool                        $fetchEager
-     * @param array                       $jsonldContext
-     * @param array                       $openapiContext
-     * @param bool                        $push
-     * @param string                      $security
-     * @param string                      $securityPostDenormalize
+     * @param bool                        $fetchEager              https://api-platform.com/docs/core/performance/#eager-loading
+     * @param array                       $jsonldContext           https://api-platform.com/docs/core/extending-jsonld-context/#extending-json-ld-and-hydra-contexts
+     * @param array                       $openapiContext          https://api-platform.com/docs/core/openapi/#using-the-openapi-and-swagger-contexts
+     * @param bool                        $push                    https://api-platform.com/docs/core/push-relations/
+     * @param string                      $security                https://api-platform.com/docs/core/security
+     * @param string                      $securityPostDenormalize https://api-platform.com/docs/core/security/#executing-access-control-rules-after-denormalization
+     * @param string[]|string             $types                   the RDF types of this property
      */
     public function __construct(
         ?string $description = null,
@@ -132,8 +131,8 @@ public function __construct(
         ?bool $required = null,
         ?bool $identifier = null,
 
-               $default = null,
-               $example = null,
+        $default = null,
+        $example = null,
 
         ?string $deprecationReason = null,
         ?bool $fetchable = null,
@@ -144,7 +143,7 @@ public function __construct(
         ?string $security = null,
         ?string $securityPostDenormalize = null,
 
-        ?array $types = [],
+        $types = [],
         ?array $builtinTypes = [],
         ?array $schema = [],
         ?bool $initializable = null,
@@ -170,7 +169,7 @@ public function __construct(
         $this->security = $security;
         $this->openapiContext = $openapiContext;
         $this->securityPostDenormalize = $securityPostDenormalize;
-        $this->types = $types;
+        $this->types = (array) $types;
         $this->builtinTypes = $builtinTypes;
         $this->schema = $schema;
         $this->initializable = $initializable;
@@ -403,10 +402,13 @@ public function getTypes(): ?array
         return $this->types;
     }
 
-    public function withTypes(array $types = []): self
+    /**
+     * @param string[]|string $types
+     */
+    public function withTypes($types = []): self
     {
         $self = clone $this;
-        $self->types = $types;
+        $self->types = (array) $types;
 
         return $self;
     }

src/Metadata/ApiResource.php

@@ -113,7 +113,7 @@ final class ApiResource
      * @param string          $uriTemplate
      * @param string          $shortName
      * @param string          $description
-     * @param string[]|string $types
+     * @param string[]|string $types                          The RDF types of this resource
      * @param array|string    $formats                        https://api-platform.com/docs/core/content-negotiation/#configuring-formats-for-a-specific-resource-or-operation
      * @param array|string    $inputFormats                   https://api-platform.com/docs/core/content-negotiation/#configuring-formats-for-a-specific-resource-or-operation
      * @param array|string    $outputFormats                  https://api-platform.com/docs/core/content-negotiation/#configuring-formats-for-a-specific-resource-or-operation