Attachables (#995)

Introduce new annotation `Attachable`

This allows to attach any data to a given annotation.
Attachables are not part of the spec but they allow to inject custom data to annotations that can then be processed by a custom processor.

Examples/misc/misc-api.php

@@ -9,7 +9,8 @@
  *         securityScheme="bearerAuth",
  *         type="http",
  *         scheme="bearer",
- *     )
+ *     ),
+ *     @OA\Attachable()
  * )
  */
 

src/Annotations/AbstractAnnotation.php

@@ -26,6 +26,12 @@ abstract class AbstractAnnotation implements \JsonSerializable
      */
     public $x = Generator::UNDEFINED;
 
+    /**
+     * Arbitrary attachables for this annotation.
+     * These will be ignored but can be used for custom processing.
+     */
+    public $attachables = Generator::UNDEFINED;
+
     /**
      * @var Context
      */
@@ -81,7 +87,7 @@ abstract class AbstractAnnotation implements \JsonSerializable
      *
      * @var array
      */
-    public static $_blacklist = ['_context', '_unmerged'];
+    public static $_blacklist = ['_context', '_unmerged', 'attachables'];
 
     public function __construct(array $properties)
     {

src/Annotations/AdditionalProperties.php

@@ -33,5 +33,6 @@ class AdditionalProperties extends Schema
         ExternalDocumentation::class => 'externalDocs',
         Xml::class => 'xml',
         AdditionalProperties::class => 'additionalProperties',
+        Attachable::class => ['attachables'],
     ];
 }

src/Annotations/Attachable.php

@@ -0,0 +1,72 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Annotations;
+
+/**
+ * @Annotation
+ *
+ * A container for custom data to be attached to an annotation.
+ * These will be ignored by swagger-php but can be used for custom processing.
+ */
+class Attachable extends AbstractAnnotation
+{
+    /**
+     * @inheritdoc
+     */
+    public static $_parents = [
+        AdditionalProperties::class,
+        Components::class,
+        Contact::class,
+        Delete::class,
+        Discriminator::class,
+        Examples::class,
+        ExternalDocumentation::class,
+        Flow::class,
+        Get::class,
+        Head::class,
+        Header::class,
+        Info::class,
+        Items::class,
+        JsonContent::class,
+        License::class,
+        Link::class,
+        MediaType::class,
+        OpenApi::class,
+        Operation::class,
+        Options::class,
+        Parameter::class,
+        Patch::class,
+        PathItem::class,
+        Post::class,
+        Property::class,
+        Put::class,
+        RequestBody::class,
+        Response::class,
+        Schema::class,
+        SecurityScheme::class,
+        Server::class,
+        ServerVariable::class,
+        Tag::class,
+        Trace::class,
+        Xml::class,
+        XmlContent::class,
+    ];
+
+    /**
+     * Allows to type hint a specific parent annotation class.
+     *
+     * Allows to implement custom annotations that are limited to a subset of potential parent
+     * annotation classes.
+     * This is most likely going to be a v4 (PHP 8.1) PHP attribute feature only.
+     *
+     * @return array List of valid parent annotation classes. If `null`` the default nesting rules apply.
+     */
+    public function allowedParents(): ?array
+    {
+        return null;
+    }
+}

src/Annotations/Components.php

@@ -106,5 +106,6 @@ class Components extends AbstractAnnotation
         Header::class => ['headers', 'header'],
         SecurityScheme::class => ['securitySchemes', 'securityScheme'],
         Link::class => ['links', 'link'],
+        Attachable::class => ['attachables'],
     ];
 }

src/Annotations/Contact.php

@@ -52,4 +52,11 @@ class Contact extends AbstractAnnotation
     public static $_parents = [
         Info::class,
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
 }

src/Annotations/Discriminator.php

@@ -57,4 +57,11 @@ class Discriminator extends AbstractAnnotation
         JsonContent::class,
         XmlContent::class,
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
 }

src/Annotations/Examples.php

@@ -80,4 +80,11 @@ class Examples extends AbstractAnnotation
         JsonContent::class,
         XmlContent::class,
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
 }

src/Annotations/ExternalDocumentation.php

@@ -65,4 +65,11 @@ class ExternalDocumentation extends AbstractAnnotation
         JsonContent::class,
         XmlContent::class,
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
 }

src/Annotations/Flow.php

@@ -79,6 +79,13 @@ class Flow extends AbstractAnnotation
         SecurityScheme::class,
     ];
 
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
+
     /** @inheritdoc */
     #[\ReturnTypeWillChange]
     public function jsonSerialize()

src/Annotations/Header.php

@@ -80,6 +80,7 @@ class Header extends AbstractAnnotation
      */
     public static $_nested = [
         Schema::class => 'schema',
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/Info.php

@@ -80,6 +80,7 @@ class Info extends AbstractAnnotation
     public static $_nested = [
         Contact::class => 'contact',
         License::class => 'license',
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/Items.php

@@ -22,6 +22,7 @@ class Items extends Schema
         ExternalDocumentation::class => 'externalDocs',
         Xml::class => 'xml',
         AdditionalProperties::class => 'additionalProperties',
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/JsonContent.php

@@ -42,5 +42,6 @@ class JsonContent extends Schema
         ExternalDocumentation::class => 'externalDocs',
         AdditionalProperties::class => 'additionalProperties',
         Examples::class => ['examples', 'example'],
+        Attachable::class => ['attachables'],
     ];
 }

src/Annotations/License.php

@@ -49,4 +49,11 @@ class License extends AbstractAnnotation
     public static $_parents = [
         Info::class,
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
 }

src/Annotations/Link.php

@@ -83,6 +83,7 @@ class Link extends AbstractAnnotation
      */
     public static $_nested = [
         Server::class => 'server',
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/MediaType.php

@@ -62,7 +62,9 @@ class MediaType extends AbstractAnnotation
     public static $_nested = [
         Schema::class => 'schema',
         Examples::class => ['examples', 'example'],
+        Attachable::class => ['attachables'],
     ];
+
     /**
      * @inheritdoc
      */

src/Annotations/OpenApi.php

@@ -115,6 +115,7 @@ class OpenApi extends AbstractAnnotation
         Components::class => 'components',
         Tag::class => ['tags'],
         ExternalDocumentation::class => 'externalDocs',
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/Operation.php

@@ -162,6 +162,7 @@ abstract class Operation extends AbstractAnnotation
         ExternalDocumentation::class => 'externalDocs',
         Server::class => ['servers'],
         RequestBody::class => 'requestBody',
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/Parameter.php

@@ -212,6 +212,7 @@ class Parameter extends AbstractAnnotation
     public static $_nested = [
         Schema::class => 'schema',
         Examples::class => ['examples', 'example'],
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/PathItem.php

@@ -133,6 +133,7 @@ class PathItem extends AbstractAnnotation
         Options::class => 'options',
         Parameter::class => ['parameters'],
         Server::class => ['servers'],
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/Property.php

@@ -49,5 +49,6 @@ class Property extends Schema
         ExternalDocumentation::class => 'externalDocs',
         Xml::class => 'xml',
         AdditionalProperties::class => 'additionalProperties',
+        Attachable::class => ['attachables'],
     ];
 }

src/Annotations/RequestBody.php

@@ -80,5 +80,6 @@ class RequestBody extends AbstractAnnotation
      */
     public static $_nested = [
         MediaType::class => ['content', 'mediaType'],
+        Attachable::class => ['attachables'],
     ];
 }

src/Annotations/Response.php

@@ -83,6 +83,7 @@ class Response extends AbstractAnnotation
         MediaType::class => ['content', 'mediaType'],
         Header::class => ['headers', 'header'],
         Link::class => ['links', 'link'],
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/Schema.php

@@ -357,6 +357,7 @@ class Schema extends AbstractAnnotation
         ExternalDocumentation::class => 'externalDocs',
         Xml::class => 'xml',
         AdditionalProperties::class => 'additionalProperties',
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/SecurityScheme.php

@@ -109,6 +109,7 @@ class SecurityScheme extends AbstractAnnotation
      */
     public static $_nested = [
         Flow::class => ['flows', 'flow'],
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/Server.php

@@ -63,6 +63,7 @@ class Server extends AbstractAnnotation
      */
     public static $_nested = [
         ServerVariable::class => ['variables', 'serverVariable'],
+        Attachable::class => ['attachables'],
     ];
 
     /**

src/Annotations/ServerVariable.php

@@ -72,4 +72,11 @@ class ServerVariable extends AbstractAnnotation
         'default' => 'string',
         'description' => 'string',
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
 }

src/Annotations/Tag.php

@@ -61,5 +61,6 @@ class Tag extends AbstractAnnotation
      */
     public static $_nested = [
         ExternalDocumentation::class => 'externalDocs',
+        Attachable::class => ['attachables'],
     ];
 }

src/Annotations/Xml.php

@@ -72,4 +72,11 @@ class Xml extends AbstractAnnotation
         Items::class,
         XmlContent::class,
     ];
+
+    /**
+     * @inheritdoc
+     */
+    public static $_nested = [
+        Attachable::class => ['attachables'],
+    ];
 }

src/Annotations/XmlContent.php

@@ -37,5 +37,6 @@ class XmlContent extends Schema
         Xml::class => 'xml',
         AdditionalProperties::class => 'additionalProperties',
         Examples::class => ['examples', 'example'],
+        Attachable::class => ['attachables'],
     ];
 }

src/Serializer.php

@@ -17,6 +17,7 @@ class Serializer
 {
     private static $VALID_ANNOTATIONS = [
         OA\AdditionalProperties::class,
+        OA\Attachable::class,
         OA\Components::class,
         OA\Contact::class,
         OA\Delete::class,