Add Encoding annotation to manage MediaType encodings (#1835)

Author: DerManoMann

phpstan-baseline.neon

@@ -84,6 +84,12 @@ parameters:
 			count: 1
 			path: src/Processors/DocBlockDescriptions.php
 
+		-
+			message: '#^Property OpenApi\\Annotations\\JsonContent\:\:\$encoding \(array\<OpenApi\\Annotations\\Encoding\>\) does not accept string\.$#'
+			identifier: assign.propertyType
+			count: 1
+			path: src/Processors/MergeJsonContent.php
+
 		-
 			message: '#^Property OpenApi\\Annotations\\Schema\:\:\$examples \(array\<OpenApi\\Annotations\\Examples\>\) does not accept string\.$#'
 			identifier: assign.propertyType

src/Annotations/Attachable.php

@@ -24,6 +24,7 @@ class Attachable extends AbstractAnnotation
         Contact::class,
         Delete::class,
         Discriminator::class,
+        Encoding::class,
         Examples::class,
         ExternalDocumentation::class,
         Flow::class,

src/Annotations/Encoding.php

@@ -0,0 +1,93 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Annotations;
+
+use OpenApi\Generator;
+
+/**
+ * A single encoding definition applied to a single schema property.
+ *
+ * @see [Encoding Object](https://spec.openapis.org/oas/v3.1.0.html#encoding-object)
+ *
+ * @Annotation
+ */
+class Encoding extends AbstractAnnotation
+{
+    /**
+     * The property name to which the encoding applies.
+     *
+     * @var string
+     */
+    public $property = Generator::UNDEFINED;
+
+    /**
+     * The content type.
+     *
+     * @var string
+     */
+    public $contentType = Generator::UNDEFINED;
+
+    /**
+     * Additional headers.
+     *
+     * @var Header[]
+     */
+    public $headers = Generator::UNDEFINED;
+
+    /**
+     * @var string
+     */
+    public $style = Generator::UNDEFINED;
+
+    /**
+     * @var bool
+     */
+    public $explode = Generator::UNDEFINED;
+
+    /**
+     * @var bool
+     */
+    public $allowReserved = Generator::UNDEFINED;
+
+    /**
+     * @inheritdoc
+     */
+    public static $_parents = [
+        JsonContent::class,
+        XmlContent::class,
+        MediaType::class,
+        Property::class,
+    ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Header::class => ['headers', 'header'],
+        Attachable::class => ['attachables'],
+    ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_types = [
+        'contentType' => 'string',
+    ];
+
+    /**
+     * @inheritdoc
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+        $data = parent::jsonSerialize();
+
+        unset($data->property);
+
+        return $data;
+    }
+}

src/Annotations/Header.php

@@ -95,6 +95,7 @@ class Header extends AbstractAnnotation
      * @inheritdoc
      */
     public static $_parents = [
+        Encoding::class,
         Components::class,
         Response::class,
     ];

src/Annotations/JsonContent.php

@@ -7,6 +7,7 @@
 namespace OpenApi\Annotations;
 
 use OpenApi\Annotations as OA;
+use OpenApi\Generator;
 
 /**
  * Shorthand for a json response.
@@ -31,6 +32,13 @@
  */
 class JsonContent extends Schema
 {
+    /**
+     * A map between a property name and its encoding information.
+     *
+     * @var Encoding[]
+     */
+    public $encoding = Generator::UNDEFINED;
+
     /**
      * @inheritdoc
      */
@@ -45,6 +53,7 @@ class JsonContent extends Schema
         Property::class => ['properties', 'property'],
         ExternalDocumentation::class => 'externalDocs',
         AdditionalProperties::class => 'additionalProperties',
+        Encoding::class => ['encoding', 'property'],
         Examples::class => ['examples', 'example'],
         Attachable::class => ['attachables'],
     ];

src/Annotations/MediaType.php

@@ -61,7 +61,7 @@ class MediaType extends AbstractAnnotation
      * The encoding object shall only apply to requestBody objects when the media type is multipart or
      * application/x-www-form-urlencoded.
      *
-     * @var array<string,mixed>
+     * @var Encoding[]
      */
     public $encoding = Generator::UNDEFINED;
 
@@ -71,6 +71,7 @@ class MediaType extends AbstractAnnotation
     public static $_nested = [
         Schema::class => 'schema',
         Examples::class => ['examples', 'example'],
+        Encoding::class => ['encoding', 'property'],
         Attachable::class => ['attachables'],
     ];
 

src/Annotations/OpenApi.php

@@ -214,7 +214,7 @@ public function saveAs(string $filename, string $format = 'auto'): void
     /**
      * Look up an annotation with a $ref url.
      *
-     * @param string $ref The $ref value, for example: "#/components/schemas/Product"
+     * @param string $ref The $ref value; example: "#/components/schemas/Product"
      */
     public function ref(string $ref)
     {

src/Annotations/Property.php

@@ -20,6 +20,11 @@ class Property extends Schema
      */
     public $property = Generator::UNDEFINED;
 
+    /**
+     * @var Encoding
+     */
+    public $encoding = Generator::UNDEFINED;
+
     /**
      * @inheritdoc
      */
@@ -42,6 +47,20 @@ class Property extends Schema
         ExternalDocumentation::class => 'externalDocs',
         Xml::class => 'xml',
         AdditionalProperties::class => 'additionalProperties',
+        Encoding::class => 'encoding',
         Attachable::class => ['attachables'],
     ];
+
+    /**
+     * @inheritdoc
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+        $data = parent::jsonSerialize();
+
+        unset($data->encoding);
+
+        return $data;
+    }
 }

src/Annotations/XmlContent.php

@@ -7,6 +7,7 @@
 namespace OpenApi\Annotations;
 
 use OpenApi\Annotations as OA;
+use OpenApi\Generator;
 
 /**
  * Shorthand for a xml response.
@@ -17,6 +18,13 @@
  */
 class XmlContent extends Schema
 {
+    /**
+     * A map between a property name and its encoding information.
+     *
+     * @var Encoding[]
+     */
+    public $encoding = Generator::UNDEFINED;
+
     /**
      * @inheritdoc
      */
@@ -32,6 +40,7 @@ class XmlContent extends Schema
         ExternalDocumentation::class => 'externalDocs',
         Xml::class => 'xml',
         AdditionalProperties::class => 'additionalProperties',
+        Encoding::class => ['encoding', 'property'],
         Examples::class => ['examples', 'example'],
         Attachable::class => ['attachables'],
     ];

src/Attributes/Encoding.php

@@ -0,0 +1,42 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Attributes;
+
+use OpenApi\Annotations as OA;
+use OpenApi\Generator;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class Encoding extends OA\Encoding
+{
+    /**
+     * @param Header[]                 $headers
+     * @param array<string,mixed>|null $x
+     * @param Attachable[]|null        $attachables
+     */
+    public function __construct(
+        ?string $property = null,
+        ?string $contentType = null,
+        ?array $headers = null,
+        ?string $style = null,
+        ?bool $explode = null,
+        ?bool $allowReserved = null,
+        // annotation
+        ?array $x = null,
+        ?array $attachables = null
+    ) {
+        parent::__construct([
+            'property' => $property ?? Generator::UNDEFINED,
+            'contentType' => $contentType ?? Generator::UNDEFINED,
+            'style' => $style ?? Generator::UNDEFINED,
+            'explode' => $explode ?? Generator::UNDEFINED,
+            'allowReserved' => $allowReserved ?? Generator::UNDEFINED,
+            'x' => $x ?? Generator::UNDEFINED,
+            'attachables' => $attachables ?? Generator::UNDEFINED,
+            'value' => $this->combine($headers),
+        ]);
+    }
+}