Feat: Change nullable & type for OpenApi v3.1.0 (#1502)

zircote · Nov 30, 2023 · 21366a8 · 21366a8
1 parent 5d16fec
commit 21366a8
Show file tree

Hide file tree

Showing 17 changed files with 161 additions and 40 deletions.
diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md
@@ -956,10 +956,12 @@ An object instance is valid against this property if its number of properties is
   <dt><strong>required</strong> : <span style="font-family: monospace;">string[]</span></dt>
   <dd><p>An object instance is valid against this property if its property set contains all elements in this property's<br />
 array value.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;</span></dt>
   <dd><p>The type of the schema/property.<br />
 <br />
-The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
+OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".<br />
+<br />
+Since OpenApi v3.1 an array of types may be used.</p></dd>
   <dt><strong>format</strong> : <span style="font-family: monospace;">string</span></dt>
   <dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
   <dt><strong>collectionFormat</strong> : <span style="font-family: monospace;">string</span></dt>
@@ -1040,7 +1042,10 @@ To represent examples that cannot naturally be represented in JSON or YAML, a st
 contain the example with escaping where necessary.</p></dd>
   <dt><strong>nullable</strong> : <span style="font-family: monospace;">bool</span></dt>
   <dd><p>Allows sending a null value for the defined schema.<br />
-Default value is false.</p></dd>
+Default value is false.<br />
+<br />
+This must not be used when using OpenApi version 3.1,<br />
+instead make the "type" property an array and add "null" as a possible type.</p></dd>
   <dt><strong>deprecated</strong> : <span style="font-family: monospace;">bool</span></dt>
   <dd><p>Specifies that a schema is deprecated and should be transitioned out of usage.<br />
 Default value is false.</p></dd>
@@ -1093,7 +1098,7 @@ defined by this property's value.</p></dd>
   <dd><p>The relative or absolute path to a security scheme.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
   <dt><strong>securityScheme</strong> : <span style="font-family: monospace;">string</span></dt>
   <dd><p>The key into OpenApi->security array.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;</span></dt>
   <dd><p>The type of the security scheme.</p></dd>
   <dt><strong>description</strong> : <span style="font-family: monospace;">string</span></dt>
   <dd><p>A short description for security scheme.</p></dd>

diff --git a/docs/reference/attributes.md b/docs/reference/attributes.md
@@ -44,10 +44,12 @@ array value.</p></dd>
   <dd><p>A collection of properties to define for an object.<br />
 <br />
 Each property is represented as an instance of the <a href="#property">Property</a> class.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;|null</span></dt>
   <dd><p>The type of the schema/property.<br />
 <br />
-The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
+OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".<br />
+<br />
+Since OpenApi v3.1 an array of types may be used.</p></dd>
   <dt><strong>format</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
   <dt><strong>items</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Items|null</span></dt>
@@ -139,7 +141,10 @@ To represent examples that cannot naturally be represented in JSON or YAML, a st
 contain the example with escaping where necessary.</p></dd>
   <dt><strong>nullable</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Allows sending a null value for the defined schema.<br />
-Default value is false.</p></dd>
+Default value is false.<br />
+<br />
+This must not be used when using OpenApi version 3.1,<br />
+instead make the "type" property an array and add "null" as a possible type.</p></dd>
   <dt><strong>deprecated</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Specifies that a schema is deprecated and should be transitioned out of usage.<br />
 Default value is false.</p></dd>
@@ -1002,10 +1007,12 @@ array value.</p></dd>
   <dd><p>A collection of properties to define for an object.<br />
 <br />
 Each property is represented as an instance of the <a href="#property">Property</a> class.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;|null</span></dt>
   <dd><p>The type of the schema/property.<br />
 <br />
-The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
+OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".<br />
+<br />
+Since OpenApi v3.1 an array of types may be used.</p></dd>
   <dt><strong>format</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
   <dt><strong>items</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Items|null</span></dt>
@@ -1097,7 +1104,10 @@ To represent examples that cannot naturally be represented in JSON or YAML, a st
 contain the example with escaping where necessary.</p></dd>
   <dt><strong>nullable</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Allows sending a null value for the defined schema.<br />
-Default value is false.</p></dd>
+Default value is false.<br />
+<br />
+This must not be used when using OpenApi version 3.1,<br />
+instead make the "type" property an array and add "null" as a possible type.</p></dd>
   <dt><strong>deprecated</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Specifies that a schema is deprecated and should be transitioned out of usage.<br />
 Default value is false.</p></dd>
@@ -1160,10 +1170,12 @@ array value.</p></dd>
   <dd><p>A collection of properties to define for an object.<br />
 <br />
 Each property is represented as an instance of the <a href="#property">Property</a> class.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;|null</span></dt>
   <dd><p>The type of the schema/property.<br />
 <br />
-The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
+OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".<br />
+<br />
+Since OpenApi v3.1 an array of types may be used.</p></dd>
   <dt><strong>format</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
   <dt><strong>items</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Items|null</span></dt>
@@ -1255,7 +1267,10 @@ To represent examples that cannot naturally be represented in JSON or YAML, a st
 contain the example with escaping where necessary.</p></dd>
   <dt><strong>nullable</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Allows sending a null value for the defined schema.<br />
-Default value is false.</p></dd>
+Default value is false.<br />
+<br />
+This must not be used when using OpenApi version 3.1,<br />
+instead make the "type" property an array and add "null" as a possible type.</p></dd>
   <dt><strong>deprecated</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Specifies that a schema is deprecated and should be transitioned out of usage.<br />
 Default value is false.</p></dd>
@@ -2024,10 +2039,12 @@ array value.</p></dd>
   <dd><p>A collection of properties to define for an object.<br />
 <br />
 Each property is represented as an instance of the <a href="#property">Property</a> class.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;|null</span></dt>
   <dd><p>The type of the schema/property.<br />
 <br />
-The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
+OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".<br />
+<br />
+Since OpenApi v3.1 an array of types may be used.</p></dd>
   <dt><strong>format</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
   <dt><strong>items</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Items|null</span></dt>
@@ -2119,7 +2136,10 @@ To represent examples that cannot naturally be represented in JSON or YAML, a st
 contain the example with escaping where necessary.</p></dd>
   <dt><strong>nullable</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Allows sending a null value for the defined schema.<br />
-Default value is false.</p></dd>
+Default value is false.<br />
+<br />
+This must not be used when using OpenApi version 3.1,<br />
+instead make the "type" property an array and add "null" as a possible type.</p></dd>
   <dt><strong>deprecated</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Specifies that a schema is deprecated and should be transitioned out of usage.<br />
 Default value is false.</p></dd>
@@ -2470,10 +2490,12 @@ array value.</p></dd>
   <dd><p>A collection of properties to define for an object.<br />
 <br />
 Each property is represented as an instance of the <a href="#property">Property</a> class.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;|null</span></dt>
   <dd><p>The type of the schema/property.<br />
 <br />
-The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
+OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".<br />
+<br />
+Since OpenApi v3.1 an array of types may be used.</p></dd>
   <dt><strong>format</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
   <dt><strong>items</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Items|null</span></dt>
@@ -2565,7 +2587,10 @@ To represent examples that cannot naturally be represented in JSON or YAML, a st
 contain the example with escaping where necessary.</p></dd>
   <dt><strong>nullable</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Allows sending a null value for the defined schema.<br />
-Default value is false.</p></dd>
+Default value is false.<br />
+<br />
+This must not be used when using OpenApi version 3.1,<br />
+instead make the "type" property an array and add "null" as a possible type.</p></dd>
   <dt><strong>deprecated</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Specifies that a schema is deprecated and should be transitioned out of usage.<br />
 Default value is false.</p></dd>
@@ -2610,7 +2635,7 @@ These will be ignored but can be used for custom processing.</p></dd>
   <dd><p>The relative or absolute path to a security scheme.</p><p><i>See</i>: <a href="https://swagger.io/docs/specification/using-ref/">Using refs</a></p></dd>
   <dt><strong>securityScheme</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The key into OpenApi->security array.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;|null</span></dt>
   <dd><p>The type of the security scheme.</p></dd>
   <dt><strong>description</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>A short description for security scheme.</p></dd>
@@ -2918,10 +2943,12 @@ array value.</p></dd>
   <dd><p>A collection of properties to define for an object.<br />
 <br />
 Each property is represented as an instance of the <a href="#property">Property</a> class.</p></dd>
-  <dt><strong>type</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dt><strong>type</strong> : <span style="font-family: monospace;">string|non-empty-array&lt;string&gt;|null</span></dt>
   <dd><p>The type of the schema/property.<br />
 <br />
-The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".</p></dd>
+OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".<br />
+<br />
+Since OpenApi v3.1 an array of types may be used.</p></dd>
   <dt><strong>format</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The extending format for the previously mentioned type. See Data Type Formats for further details.</p></dd>
   <dt><strong>items</strong> : <span style="font-family: monospace;">OpenApi\Attributes\Items|null</span></dt>
@@ -3013,7 +3040,10 @@ To represent examples that cannot naturally be represented in JSON or YAML, a st
 contain the example with escaping where necessary.</p></dd>
   <dt><strong>nullable</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Allows sending a null value for the defined schema.<br />
-Default value is false.</p></dd>
+Default value is false.<br />
+<br />
+This must not be used when using OpenApi version 3.1,<br />
+instead make the "type" property an array and add "null" as a possible type.</p></dd>
   <dt><strong>deprecated</strong> : <span style="font-family: monospace;">bool|null</span></dt>
   <dd><p>Specifies that a schema is deprecated and should be transitioned out of usage.<br />
 Default value is false.</p></dd>

diff --git a/src/Annotations/Schema.php b/src/Annotations/Schema.php
@@ -91,9 +91,11 @@ class Schema extends AbstractAnnotation
     /**
      * The type of the schema/property.
      *
-     * The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".
+     * OpenApi v3.0: The value MUST be one of "string", "number", "integer", "boolean", "array" or "object".
      *
-     * @var string
+     * Since OpenApi v3.1 an array of types may be used.
+     *
+     * @var string|non-empty-array<string>
      */
     public $type = Generator::UNDEFINED;
 
@@ -325,7 +327,12 @@ class Schema extends AbstractAnnotation
      * Allows sending a null value for the defined schema.
      * Default value is false.
      *
+     * This must not be used when using OpenApi version 3.1,
+     * instead make the "type" property an array and add "null" as a possible type.
+     *
      * @var bool
+     *
+     * @see https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
      */
     public $nullable = Generator::UNDEFINED;
 

diff --git a/src/Annotations/SecurityScheme.php b/src/Annotations/SecurityScheme.php
@@ -34,7 +34,7 @@ class SecurityScheme extends AbstractAnnotation
     /**
      * The type of the security scheme.
      *
-     * @var string
+     * @var string|non-empty-array<string>
      */
     public $type = Generator::UNDEFINED;
 

diff --git a/src/Attributes/AdditionalProperties.php b/src/Attributes/AdditionalProperties.php
@@ -12,6 +12,7 @@
 class AdditionalProperties extends \OpenApi\Annotations\AdditionalProperties
 {
     /**
+     * @param string|non-empty-array<string>|null                    $type
      * @param string|class-string|object|null                        $ref
      * @param string[]                                               $required
      * @param Property[]                                             $properties
@@ -34,7 +35,7 @@ public function __construct(
         ?int $minProperties = null,
         ?array $required = null,
         ?array $properties = null,
-        ?string $type = null,
+        string|array|null $type = null,
         ?string $format = null,
         ?Items $items = null,
         ?string $collectionFormat = null,

diff --git a/src/Attributes/Items.php b/src/Attributes/Items.php
@@ -12,6 +12,7 @@
 class Items extends \OpenApi\Annotations\Items
 {
     /**
+     * @param string|non-empty-array<string>|null                    $type
      * @param string|class-string|object|null                        $ref
      * @param string[]                                               $required
      * @param Property[]                                             $properties
@@ -34,7 +35,7 @@ public function __construct(
         ?int $minProperties = null,
         ?array $required = null,
         ?array $properties = null,
-        ?string $type = null,
+        string|array|null $type = null,
         ?string $format = null,
         ?Items $items = null,
         ?string $collectionFormat = null,

diff --git a/src/Attributes/JsonContent.php b/src/Attributes/JsonContent.php
@@ -12,6 +12,7 @@
 class JsonContent extends \OpenApi\Annotations\JsonContent
 {
     /**
+     * @param string|non-empty-array<string>|null                    $type
      * @param string|class-string|object|null                        $ref
      * @param array<string,Examples>                                 $examples
      * @param string[]                                               $required
@@ -36,7 +37,7 @@ public function __construct(
         ?int $minProperties = null,
         ?array $required = null,
         ?array $properties = null,
-        ?string $type = null,
+        string|array|null $type = null,
         ?string $format = null,
         ?Items $items = null,
         ?string $collectionFormat = null,

diff --git a/src/Attributes/Property.php b/src/Attributes/Property.php
@@ -12,6 +12,7 @@
 class Property extends \OpenApi\Annotations\Property
 {
     /**
+     * @param string|non-empty-array<string>|null                    $type
      * @param string|class-string|object|null                        $ref
      * @param string[]                                               $required
      * @param Property[]                                             $properties
@@ -35,7 +36,7 @@ public function __construct(
         ?int $minProperties = null,
         ?array $required = null,
         ?array $properties = null,
-        ?string $type = null,
+        string|array|null $type = null,
         ?string $format = null,
         ?Items $items = null,
         ?string $collectionFormat = null,

diff --git a/src/Attributes/Schema.php b/src/Attributes/Schema.php
@@ -12,6 +12,7 @@
 class Schema extends \OpenApi\Annotations\Schema
 {
     /**
+     * @param string|non-empty-array<string>|null                    $type
      * @param string|class-string|object|null                        $ref
      * @param string[]                                               $required
      * @param Property[]                                             $properties
@@ -35,7 +36,7 @@ public function __construct(
         ?int $minProperties = null,
         ?array $required = null,
         ?array $properties = null,
-        ?string $type = null,
+        string|array|null $type = null,
         ?string $format = null,
         ?Items $items = null,
         ?string $collectionFormat = null,