feat(openapi): support OpenAPI 3.2.0

Add the fields introduced by OpenAPI 3.2.0 to the model classes and
bump the declared version from 3.1.0 to 3.2.0.

- OpenApi: $self
- Server: name
- Tag: summary, parent, kind
- PathItem: query (QUERY method), additionalOperations
- MediaType: itemSchema, prefixEncoding, itemEncoding (streaming)
- Encoding: encoding, prefixEncoding, itemEncoding
- Response: summary
- Example: dataValue, serializedValue
- Components: mediaTypes
- SecurityScheme: oauth2MetadataUrl, deprecated
- OAuthFlows: deviceAuthorization
- OAuthFlow: deviceAuthorizationUrl

All additions are new constructor params at the end with null
defaults; with SKIP_NULL_VALUES they never appear in output unless
set. The 3.0.0 downgrade via ?spec_version=3.0.0 is unchanged.

Author: soyuka

src/OpenApi/Model/Components.php

@@ -30,8 +30,9 @@ final class Components
      * @param \ArrayObject<string, Link>|\ArrayObject<string, Reference>                                   $links
      * @param \ArrayObject<string, array<string, PathItem>>|\ArrayObject<string, array<string, Reference>> $callbacks
      * @param \ArrayObject<string, PathItem>|\ArrayObject<string, Reference>                               $pathItems
+     * @param \ArrayObject<string, MediaType>|\ArrayObject<string, Reference>                              $mediaTypes
      */
-    public function __construct(?\ArrayObject $schemas = null, private ?\ArrayObject $responses = null, private ?\ArrayObject $parameters = null, private ?\ArrayObject $examples = null, private ?\ArrayObject $requestBodies = null, private ?\ArrayObject $headers = null, private ?\ArrayObject $securitySchemes = null, private ?\ArrayObject $links = null, private ?\ArrayObject $callbacks = null, private ?\ArrayObject $pathItems = null)
+    public function __construct(?\ArrayObject $schemas = null, private ?\ArrayObject $responses = null, private ?\ArrayObject $parameters = null, private ?\ArrayObject $examples = null, private ?\ArrayObject $requestBodies = null, private ?\ArrayObject $headers = null, private ?\ArrayObject $securitySchemes = null, private ?\ArrayObject $links = null, private ?\ArrayObject $callbacks = null, private ?\ArrayObject $pathItems = null, private ?\ArrayObject $mediaTypes = null)
     {
         $schemas?->ksort();
 
@@ -88,6 +89,11 @@ public function getPathItems(): ?\ArrayObject
         return $this->pathItems;
     }
 
+    public function getMediaTypes(): ?\ArrayObject
+    {
+        return $this->mediaTypes;
+    }
+
     public function withSchemas(\ArrayObject $schemas): self
     {
         $clone = clone $this;
@@ -167,4 +173,12 @@ public function withPathItems(\ArrayObject $pathItems): self
 
         return $clone;
     }
+
+    public function withMediaTypes(\ArrayObject $mediaTypes): self
+    {
+        $clone = clone $this;
+        $clone->mediaTypes = $mediaTypes;
+
+        return $clone;
+    }
 }

src/OpenApi/Model/Encoding.php

@@ -17,7 +17,10 @@ final class Encoding
 {
     use ExtensionTrait;
 
-    public function __construct(private string $contentType = '', private ?\ArrayObject $headers = null, private string $style = '', private bool $explode = false, private bool $allowReserved = false)
+    /**
+     * @param array<int, Encoding>|null $prefixEncoding
+     */
+    public function __construct(private string $contentType = '', private ?\ArrayObject $headers = null, private string $style = '', private bool $explode = false, private bool $allowReserved = false, private ?\ArrayObject $encoding = null, private ?array $prefixEncoding = null, private ?self $itemEncoding = null)
     {
     }
 
@@ -56,6 +59,24 @@ public function getAllowReserved(): bool
         return $this->allowReserved;
     }
 
+    public function getEncoding(): ?\ArrayObject
+    {
+        return $this->encoding;
+    }
+
+    /**
+     * @return array<int, Encoding>|null
+     */
+    public function getPrefixEncoding(): ?array
+    {
+        return $this->prefixEncoding;
+    }
+
+    public function getItemEncoding(): ?self
+    {
+        return $this->itemEncoding;
+    }
+
     public function withContentType(string $contentType): self
     {
         $clone = clone $this;
@@ -95,4 +116,31 @@ public function withAllowReserved(bool $allowReserved): self
 
         return $clone;
     }
+
+    public function withEncoding(?\ArrayObject $encoding): self
+    {
+        $clone = clone $this;
+        $clone->encoding = $encoding;
+
+        return $clone;
+    }
+
+    /**
+     * @param array<int, Encoding>|null $prefixEncoding
+     */
+    public function withPrefixEncoding(?array $prefixEncoding): self
+    {
+        $clone = clone $this;
+        $clone->prefixEncoding = $prefixEncoding;
+
+        return $clone;
+    }
+
+    public function withItemEncoding(self $itemEncoding): self
+    {
+        $clone = clone $this;
+        $clone->itemEncoding = $itemEncoding;
+
+        return $clone;
+    }
 }

src/OpenApi/Model/Example.php

@@ -17,7 +17,7 @@ final class Example
 {
     use ExtensionTrait;
 
-    public function __construct(private ?string $summary = null, private ?string $description = null, private mixed $value = null, private ?string $externalValue = null)
+    public function __construct(private ?string $summary = null, private ?string $description = null, private mixed $value = null, private ?string $externalValue = null, private mixed $dataValue = null, private ?string $serializedValue = null)
     {
     }
 
@@ -72,4 +72,30 @@ public function withExternalValue(string $externalValue): self
 
         return $clone;
     }
+
+    public function getDataValue(): mixed
+    {
+        return $this->dataValue;
+    }
+
+    public function withDataValue(mixed $dataValue): self
+    {
+        $clone = clone $this;
+        $clone->dataValue = $dataValue;
+
+        return $clone;
+    }
+
+    public function getSerializedValue(): ?string
+    {
+        return $this->serializedValue;
+    }
+
+    public function withSerializedValue(string $serializedValue): self
+    {
+        $clone = clone $this;
+        $clone->serializedValue = $serializedValue;
+
+        return $clone;
+    }
 }

src/OpenApi/Model/MediaType.php

@@ -17,7 +17,10 @@ final class MediaType
 {
     use ExtensionTrait;
 
-    public function __construct(private ?\ArrayObject $schema = null, private mixed $example = null, private ?\ArrayObject $examples = null, private ?Encoding $encoding = null)
+    /**
+     * @param array<int, Encoding>|null $prefixEncoding
+     */
+    public function __construct(private ?\ArrayObject $schema = null, private mixed $example = null, private ?\ArrayObject $examples = null, private ?Encoding $encoding = null, private ?\ArrayObject $itemSchema = null, private ?array $prefixEncoding = null, private ?Encoding $itemEncoding = null)
     {
     }
 
@@ -41,6 +44,24 @@ public function getEncoding(): ?Encoding
         return $this->encoding;
     }
 
+    public function getItemSchema(): ?\ArrayObject
+    {
+        return $this->itemSchema;
+    }
+
+    /**
+     * @return array<int, Encoding>|null
+     */
+    public function getPrefixEncoding(): ?array
+    {
+        return $this->prefixEncoding;
+    }
+
+    public function getItemEncoding(): ?Encoding
+    {
+        return $this->itemEncoding;
+    }
+
     public function withSchema(\ArrayObject $schema): self
     {
         $clone = clone $this;
@@ -72,4 +93,31 @@ public function withEncoding(Encoding $encoding): self
 
         return $clone;
     }
+
+    public function withItemSchema(\ArrayObject $itemSchema): self
+    {
+        $clone = clone $this;
+        $clone->itemSchema = $itemSchema;
+
+        return $clone;
+    }
+
+    /**
+     * @param array<int, Encoding>|null $prefixEncoding
+     */
+    public function withPrefixEncoding(?array $prefixEncoding): self
+    {
+        $clone = clone $this;
+        $clone->prefixEncoding = $prefixEncoding;
+
+        return $clone;
+    }
+
+    public function withItemEncoding(Encoding $itemEncoding): self
+    {
+        $clone = clone $this;
+        $clone->itemEncoding = $itemEncoding;
+
+        return $clone;
+    }
 }

src/OpenApi/Model/OAuthFlow.php

@@ -17,7 +17,7 @@ final class OAuthFlow
 {
     use ExtensionTrait;
 
-    public function __construct(private ?string $authorizationUrl = null, private ?string $tokenUrl = null, private ?string $refreshUrl = null, private ?\ArrayObject $scopes = null)
+    public function __construct(private ?string $authorizationUrl = null, private ?string $tokenUrl = null, private ?string $refreshUrl = null, private ?\ArrayObject $scopes = null, private ?string $deviceAuthorizationUrl = null)
     {
     }
 
@@ -41,6 +41,11 @@ public function getScopes(): \ArrayObject
         return $this->scopes;
     }
 
+    public function getDeviceAuthorizationUrl(): ?string
+    {
+        return $this->deviceAuthorizationUrl;
+    }
+
     public function withAuthorizationUrl(string $authorizationUrl): self
     {
         $clone = clone $this;
@@ -72,4 +77,12 @@ public function withScopes(\ArrayObject $scopes): self
 
         return $clone;
     }
+
+    public function withDeviceAuthorizationUrl(string $deviceAuthorizationUrl): self
+    {
+        $clone = clone $this;
+        $clone->deviceAuthorizationUrl = $deviceAuthorizationUrl;
+
+        return $clone;
+    }
 }

src/OpenApi/Model/OAuthFlows.php

@@ -17,7 +17,7 @@ final class OAuthFlows
 {
     use ExtensionTrait;
 
-    public function __construct(private ?OAuthFlow $implicit = null, private ?OAuthFlow $password = null, private ?OAuthFlow $clientCredentials = null, private ?OAuthFlow $authorizationCode = null)
+    public function __construct(private ?OAuthFlow $implicit = null, private ?OAuthFlow $password = null, private ?OAuthFlow $clientCredentials = null, private ?OAuthFlow $authorizationCode = null, private ?OAuthFlow $deviceAuthorization = null)
     {
     }
 
@@ -41,6 +41,11 @@ public function getAuthorizationCode(): ?OAuthFlow
         return $this->authorizationCode;
     }
 
+    public function getDeviceAuthorization(): ?OAuthFlow
+    {
+        return $this->deviceAuthorization;
+    }
+
     public function withImplicit(OAuthFlow $implicit): self
     {
         $clone = clone $this;
@@ -72,4 +77,12 @@ public function withAuthorizationCode(OAuthFlow $authorizationCode): self
 
         return $clone;
     }
+
+    public function withDeviceAuthorization(OAuthFlow $deviceAuthorization): self
+    {
+        $clone = clone $this;
+        $clone->deviceAuthorization = $deviceAuthorization;
+
+        return $clone;
+    }
 }

src/OpenApi/Model/PathItem.php

@@ -19,7 +19,7 @@ final class PathItem
 
     public static array $methods = ['GET', 'PUT', 'POST', 'DELETE', 'OPTIONS', 'HEAD', 'PATCH', 'TRACE'];
 
-    public function __construct(private ?string $ref = null, private ?string $summary = null, private ?string $description = null, private ?Operation $get = null, private ?Operation $put = null, private ?Operation $post = null, private ?Operation $delete = null, private ?Operation $options = null, private ?Operation $head = null, private ?Operation $patch = null, private ?Operation $trace = null, private ?array $servers = null, private ?array $parameters = null)
+    public function __construct(private ?string $ref = null, private ?string $summary = null, private ?string $description = null, private ?Operation $get = null, private ?Operation $put = null, private ?Operation $post = null, private ?Operation $delete = null, private ?Operation $options = null, private ?Operation $head = null, private ?Operation $patch = null, private ?Operation $trace = null, private ?array $servers = null, private ?array $parameters = null, private ?Operation $query = null, private ?array $additionalOperations = null)
     {
     }
 
@@ -88,6 +88,19 @@ public function getParameters(): ?array
         return $this->parameters;
     }
 
+    public function getQuery(): ?Operation
+    {
+        return $this->query;
+    }
+
+    /**
+     * @return array<string, Operation>|null
+     */
+    public function getAdditionalOperations(): ?array
+    {
+        return $this->additionalOperations;
+    }
+
     public function withRef(string $ref): self
     {
         $clone = clone $this;
@@ -191,4 +204,23 @@ public function withParameters(?array $parameters = null): self
 
         return $clone;
     }
+
+    public function withQuery(?Operation $query): self
+    {
+        $clone = clone $this;
+        $clone->query = $query;
+
+        return $clone;
+    }
+
+    /**
+     * @param array<string, Operation>|null $additionalOperations
+     */
+    public function withAdditionalOperations(?array $additionalOperations = null): self
+    {
+        $clone = clone $this;
+        $clone->additionalOperations = $additionalOperations;
+
+        return $clone;
+    }
 }

src/OpenApi/Model/Response.php

@@ -17,7 +17,7 @@ final class Response
 {
     use ExtensionTrait;
 
-    public function __construct(private ?string $description = null, private ?\ArrayObject $content = null, private ?\ArrayObject $headers = null, private ?\ArrayObject $links = null)
+    public function __construct(private ?string $description = null, private ?\ArrayObject $content = null, private ?\ArrayObject $headers = null, private ?\ArrayObject $links = null, private ?string $summary = null)
     {
     }
 
@@ -41,6 +41,11 @@ public function getLinks(): ?\ArrayObject
         return $this->links;
     }
 
+    public function getSummary(): ?string
+    {
+        return $this->summary;
+    }
+
     public function withDescription(string $description): self
     {
         $clone = clone $this;
@@ -72,4 +77,12 @@ public function withLinks(\ArrayObject $links): self
 
         return $clone;
     }
+
+    public function withSummary(string $summary): self
+    {
+        $clone = clone $this;
+        $clone->summary = $summary;
+
+        return $clone;
+    }
 }