feat: document event by combining attributes and reflection

src/Attribute/AbstractProperty.php

@@ -4,7 +4,7 @@
 
 namespace Ferror\AsyncapiDocBundle\Attribute;
 
-abstract class AbstractProperty
+abstract class AbstractProperty implements PropertyInterface
 {
     public function __construct(
         public string $name,

src/Attribute/Message.php

@@ -8,10 +8,10 @@
 use Ferror\AsyncapiDocBundle\Schema\V2\ChannelType;
 
 #[Attribute(Attribute::TARGET_CLASS)]
-class Message implements PropertyInterface
+class Message
 {
     /**
-     * @param PropertyInterface[] $properties
+     * @param array<Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject> $properties
      */
     public function __construct(
         public readonly string $name,
@@ -31,8 +31,29 @@ public function toArray(): array
         ];
     }
 
-    public function addProperty(PropertyInterface $property): void
+    public function addProperty(Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject $property): void
     {
         $this->properties[] = $property;
     }
+
+    public function enrich(self $self): self
+    {
+        // UPDATE EXISTING
+        foreach ($this->properties as $property) {
+            foreach ($self->properties as $selfProperty) {
+                $property->enrich($selfProperty);
+            }
+        }
+
+        // ADD MISSING
+        $propertiesNames = array_map(fn ($property) => $property->name, $this->properties);
+
+        foreach ($self->properties as $property) {
+            if (!in_array($property->name, $propertiesNames, true)) {
+                $this->properties[] = $property;
+            }
+        }
+
+        return $this;
+    }
 }

src/Attribute/Property.php

@@ -9,14 +9,14 @@
 use Ferror\AsyncapiDocBundle\Schema\PropertyType;
 
 #[Attribute(Attribute::TARGET_PROPERTY)]
-class Property extends AbstractProperty implements PropertyInterface
+class Property extends AbstractProperty
 {
     public function __construct(
         string $name,
         string $description = '',
-        public readonly PropertyType $type = PropertyType::STRING,
-        public readonly ?Format $format = null,
-        public readonly ?string $example = null,
+        public PropertyType $type = PropertyType::STRING,
+        public ?Format $format = null,
+        public ?string $example = null,
         bool $required = true,
     ) {
         parent::__construct($name, $description, $required);
@@ -30,4 +30,25 @@ public function toArray(): array
             'example' => $this->example,
         ]);
     }
+
+    public function enrich(Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject $property): void
+    {
+        if ($property->name === $this->name && $property::class === $this::class) {
+            if (empty($this->format)) {
+                $this->format = $property->format;
+            }
+
+            if ($this->type !== $property->type && $this->type === PropertyType::STRING) {
+                $this->type = $property->type;
+            }
+
+            if (empty($this->example)) {
+                $this->example = $property->example;
+            }
+
+            if (empty($this->description)) {
+                $this->description = $property->description;
+            }
+        }
+    }
 }

src/Attribute/PropertyArray.php

@@ -9,7 +9,7 @@
 use Ferror\AsyncapiDocBundle\Schema\PropertyType;
 
 #[Attribute(Attribute::TARGET_PROPERTY)]
-class PropertyArray extends AbstractProperty implements PropertyInterface
+class PropertyArray extends AbstractProperty
 {
     public function __construct(
         string $name,
@@ -31,4 +31,8 @@ public function toArray(): array
             'itemsType' => $this->itemsType->value,
         ]);
     }
+
+    public function enrich(Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject $property): void
+    {
+    }
 }

src/Attribute/PropertyArrayObject.php

@@ -8,7 +8,7 @@
 use Ferror\AsyncapiDocBundle\Schema\Format;
 
 #[Attribute(Attribute::TARGET_PROPERTY)]
-class PropertyArrayObject extends AbstractProperty implements PropertyInterface
+class PropertyArrayObject extends AbstractProperty
 {
     public function __construct(
         string $name,
@@ -29,4 +29,8 @@ public function toArray(): array
             'example' => $this->example,
         ]);
     }
+
+    public function enrich(Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject $property): void
+    {
+    }
 }

src/Attribute/PropertyEnum.php

@@ -7,12 +7,14 @@
 use Attribute;
 use Ferror\AsyncapiDocBundle\PropertyTypeTranslator;
 use Ferror\AsyncapiDocBundle\Schema\Format;
+use Ferror\AsyncapiDocBundle\Schema\PropertyType;
 use InvalidArgumentException;
 use ReflectionEnum;
 use ReflectionEnumBackedCase;
+use ReflectionException;
 
 #[Attribute(Attribute::TARGET_PROPERTY)]
-class PropertyEnum extends AbstractProperty implements PropertyInterface
+class PropertyEnum extends AbstractProperty
 {
     public function __construct(
         string $name,
@@ -25,6 +27,9 @@ public function __construct(
         parent::__construct($name, $description, $required);
     }
 
+    /**
+     * @throws ReflectionException
+     */
     public function toArray(): array
     {
         $enum = new ReflectionEnum($this->enum);
@@ -43,4 +48,17 @@ public function toArray(): array
             'example' => $this->example,
         ]);
     }
+
+    public function enrich(Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject $property): void
+    {
+        if ($property->name === $this->name && $property::class === $this::class) {
+            if (empty($this->format)) {
+                $this->format = $property->format;
+            }
+
+            if (empty($this->example)) {
+                $this->example = $property->example;
+            }
+        }
+    }
 }

src/Attribute/PropertyInterface.php

@@ -7,4 +7,6 @@
 interface PropertyInterface
 {
     public function toArray(): array;
+
+    public function enrich(Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject $property): void;
 }

src/Attribute/PropertyObject.php

@@ -7,7 +7,7 @@
 use Attribute;
 
 #[Attribute(Attribute::TARGET_PROPERTY)]
-class PropertyObject extends AbstractProperty implements PropertyInterface
+class PropertyObject extends AbstractProperty
 {
     public function __construct(
         string $name,
@@ -26,4 +26,8 @@ public function toArray(): array
             'items' => array_map(static fn(PropertyInterface $property) => $property->toArray(), $this->items),
         ]);
     }
+
+    public function enrich(Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject $property): void
+    {
+    }
 }

src/DocumentationEditor.php

@@ -4,31 +4,38 @@
 
 namespace Ferror\AsyncapiDocBundle;
 
-use Ferror\AsyncapiDocBundle\DocumentationStrategy\PrioritisedDocumentationStrategy;
+
+use Ferror\AsyncapiDocBundle\Attribute\Message;
+use Ferror\AsyncapiDocBundle\DocumentationStrategy\PrioritisedDocumentationStrategyInterface;
 
 final readonly class DocumentationEditor
 {
     /**
-     * @param PrioritisedDocumentationStrategy[] $documentationStrategies
+     * @param PrioritisedDocumentationStrategyInterface[] $documentationStrategies
      */
     public function __construct(
         private array $documentationStrategies,
     ) {
     }
 
-    public function document(string $class): array
+    public function document(string $class): Message
     {
-        $result = [];
         $strategies = [];
 
         foreach ($this->documentationStrategies as $documentationStrategy) {
-            $strategies[$documentationStrategy->priority] = $documentationStrategy->strategy;
+            $strategies[$documentationStrategy::getDefaultPriority()] = $documentationStrategy;
         }
 
+        $firstStrategy = array_shift($strategies);
+
+        $documentedMessage = $firstStrategy->document($class);
+
         foreach ($strategies as $documentationStrategy) {
-            $result = array_merge($result, $documentationStrategy->document($class)->toArray());
+            $message = $documentationStrategy->document($class);
+
+            $documentedMessage = $documentedMessage->enrich($message);
         }
 
-        return $result;
+        return $documentedMessage;
     }
 }

src/DocumentationStrategy/AttributeDocumentationStrategy.php

@@ -7,14 +7,24 @@
 use Ferror\AsyncapiDocBundle\Attribute\Message;
 use ReflectionAttribute;
 use ReflectionClass;
+use ReflectionException;
 
-final readonly class AttributeDocumentationStrategy implements DocumentationStrategyInterface
+final readonly class AttributeDocumentationStrategy implements PrioritisedDocumentationStrategyInterface
 {
     public function __construct(
         private PropertyExtractor $propertyExtractor = new PropertyExtractor(),
     ) {
     }
 
+    public static function getDefaultPriority(): int
+    {
+        return 10;
+    }
+
+    /**
+     * @throws DocumentationStrategyException
+     * @throws ReflectionException
+     */
     public function document(string $class): Message
     {
         $reflection = new ReflectionClass($class);

src/DocumentationStrategy/PrioritisedDocumentationStrategyInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ferror\AsyncapiDocBundle\DocumentationStrategy;
+
+interface PrioritisedDocumentationStrategyInterface extends DocumentationStrategyInterface
+{
+    public static function getDefaultPriority(): int;
+}

src/DocumentationStrategy/PropertyExtractor.php

@@ -13,15 +13,13 @@
 use ReflectionAttribute;
 use ReflectionClass;
 use ReflectionException;
-use RuntimeException;
 
 class PropertyExtractor
 {
     /**
-     * @return iterable<PropertyInterface>
+     * @return iterable<Property|PropertyArray|PropertyEnum|PropertyObject|PropertyArrayObject>
      *
      * @throws ReflectionException
-     * @throws RuntimeException
      */
     public function extract(string $class): iterable
     {
@@ -53,14 +51,12 @@ public function extract(string $class): iterable
                 $propertyAttributes = $property->getAttributes(PropertyArrayObject::class);
             }
 
-            if (empty($propertyAttributes)) {
-                throw new RuntimeException('Property attribute for ' . $property->name . ' not found');
-            }
+            if ($propertyAttributes) {
+                $propertyAttribute = $propertyAttributes[0]->newInstance();
+                $propertyAttribute->name = $property->name;
 
-            $propertyAttribute = $propertyAttributes[0]->newInstance();
-            $propertyAttribute->name = $property->name;
-
-            yield $propertyAttribute;
+                yield $propertyAttribute;
+            }
         }
     }
 }

src/DocumentationStrategy/ReflectionDocumentationStrategy.php

@@ -12,8 +12,13 @@
 use ReflectionException;
 use ReflectionNamedType;
 
-final readonly class ReflectionDocumentationStrategy implements DocumentationStrategyInterface
+final readonly class ReflectionDocumentationStrategy implements PrioritisedDocumentationStrategyInterface
 {
+    public static function getDefaultPriority(): int
+    {
+        return 20;
+    }
+
     /**
      * @param class-string $class
      *
@@ -38,13 +43,25 @@ public function document(string $class): Message
             $type = $property->getType();
             $name = $property->getName();
 
-            $message->addProperty(
-                new Property(
-                    name: $name,
-                    type: PropertyType::fromNative($type?->getName()),
-                    required: $type && !$type->allowsNull(),
-                )
-            );
+            if (null === $type) {
+                break;
+            }
+
+            // ATM we don't support array types in ReflectionStrategy
+            if (in_array($type->getName(), ['array', 'object', 'resource'])) {
+                break;
+            }
+
+            // ATM we support only builtin types like integer, string, boolean, float
+            if ($type->isBuiltin()) {
+                $message->addProperty(
+                    new Property(
+                        name: $name,
+                        type: PropertyType::fromNative($type->getName()),
+                        required: !$type->allowsNull(),
+                    )
+                );
+            }
         }
 
         return $message;