Centralize all pure JSON Schema properties (#1960)

Author: DerManoMann

docs/examples/specs/api/attributes/Product.php

@@ -32,7 +32,7 @@ class Product implements ProductInterface
     public function __construct(
         #[OAT\Property]
         public int $quantity,
-        #[OAT\Property(default: null, example: null)]
+        #[OAT\Property(example: null, default: null)]
         public ?string $brand,
         #[OAT\Property(description: 'The colour')]
         public Colour $colour,

docs/examples/specs/api/mixed/Product.php

@@ -40,7 +40,7 @@ public function getQuantity(): int
         return 1;
     }
 
-    #[OAT\Property(default: null, example: null, nullable: true)]
+    #[OAT\Property(example: null, nullable: true, default: null)]
     public string $brand;
 
     /** @OA\Property(description="The colour") */

docs/examples/specs/polymorphism/attributes/AbstractResponsible.php

@@ -22,7 +22,7 @@ abstract class AbstractResponsible
 {
     protected const TYPE = null;
 
-    #[OAT\Property(enum: ['employee', 'assignee', 'fl'], nullable: false)]
+    #[OAT\Property(nullable: false, enum: ['employee', 'assignee', 'fl'])]
     protected string $type;
 
     public function __construct()

src/Analysers/AttributeAnnotationFactory.php

@@ -42,7 +42,7 @@ public function build(\Reflector $reflector, Context $context): array
         // no proper way to inject
         Generator::$context = $context;
 
-        /** @var OA\AbstractAnnotation[] $annotations */
+        /** @var list<OA\AbstractAnnotation> $annotations */
         $annotations = [];
         try {
             $attributeName = $this->ignoreOtherAttributes

src/Analysers/TokenScanner.php

@@ -17,14 +17,21 @@
 use PhpParser\ParserFactory;
 
 /**
- * High level, PHP token based, scanner.
+ * High-level, PHP-token-based, scanner.
  */
 class TokenScanner
 {
     /**
-     * Scan file for all classes, interfaces and traits.
+     * Scan a given file for all classes, interfaces, and traits.
      *
-     * @return string[][] File details
+     * @return array{
+     *     'uses': array<string, class-string>,
+     *     'interfaces': list<class-string>,
+     *     'traits': list<class-string>,
+     *     'enums': list<class-string>,
+     *     'methods': list<string>,
+     *     'properties': list<string>,
+     * } File details
      */
     public function scanFile(string $filename): array
     {

src/Annotations/AbstractAnnotation.php

@@ -46,7 +46,7 @@ abstract class AbstractAnnotation implements \JsonSerializable
     /**
      * The properties which are required by [the spec](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md).
      *
-     * @var string[]
+     * @var list<string>
      */
     public static $_required = [];
 
@@ -144,10 +144,10 @@ public function __construct(array $properties)
      *
      * Annotations that couldn't be merged are added to the _unmerged array.
      *
-     * @param AbstractAnnotation[] $annotations
-     * @param bool                 $ignore      Ignore unmerged annotations
+     * @param list<AbstractAnnotation> $annotations
+     * @param bool                     $ignore      Ignore unmerged annotations
      *
-     * @return AbstractAnnotation[] The unmerged annotations
+     * @return list<AbstractAnnotation> The unmerged annotations
      */
     public function merge(array $annotations, bool $ignore = false): array
     {
@@ -777,7 +777,7 @@ protected function combine(...$args): array
      *
      * @param array|object|string $classes Class(es) to shorten
      *
-     * @return string|string[] One or more shortened class names
+     * @return string|list<string> One or more shortened class names
      */
     protected static function shorten($classes)
     {

src/Annotations/Components.php

@@ -39,14 +39,14 @@ class Components extends AbstractAnnotation
     /**
      * Reusable Responses.
      *
-     * @var Response[]
+     * @var list<Response>
      */
     public $responses = Generator::UNDEFINED;
 
     /**
      * Reusable Parameters.
      *
-     * @var Parameter[]
+     * @var list<Parameter>
      */
     public $parameters = Generator::UNDEFINED;
 
@@ -60,28 +60,28 @@ class Components extends AbstractAnnotation
     /**
      * Reusable Request Bodies.
      *
-     * @var RequestBody[]
+     * @var list<RequestBody>
      */
     public $requestBodies = Generator::UNDEFINED;
 
     /**
      * Reusable Headers.
      *
-     * @var Header[]
+     * @var list<Header>
      */
     public $headers = Generator::UNDEFINED;
 
     /**
      * Reusable Security Schemes.
      *
-     * @var SecurityScheme[]
+     * @var list<SecurityScheme>
      */
     public $securitySchemes = Generator::UNDEFINED;
 
     /**
      * Reusable Links.
      *
-     * @var Link[]
+     * @var list<Link>
      */
     public $links = Generator::UNDEFINED;
 

src/Annotations/Discriminator.php

@@ -32,7 +32,7 @@ class Discriminator extends AbstractAnnotation
     /**
      * An object to hold mappings between payload values and schema names or references.
      *
-     * @var string[]
+     * @var array<string,string>
      */
     public $mapping = Generator::UNDEFINED;
 

src/Annotations/Encoding.php

@@ -34,7 +34,7 @@ class Encoding extends AbstractAnnotation
     /**
      * Additional headers.
      *
-     * @var Header[]
+     * @var list<Header>
      */
     public $headers = Generator::UNDEFINED;
 

src/Annotations/JsonContent.php

@@ -35,7 +35,7 @@ class JsonContent extends Schema
     /**
      * A map between a property name and its encoding information.
      *
-     * @var Encoding[]
+     * @var list<Encoding>
      */
     public $encoding = Generator::UNDEFINED;