Refactor AbstractAnnotation::identity() (#1962)

Author: DerManoMann

src/Annotations/AbstractAnnotation.php

@@ -474,7 +474,7 @@ public function validate(array $stack = [], array $skip = [], string $ref = '',
                 } elseif (Generator::isDefault($item->{$keyField})) {
                     $this->_context->logger->error($item->identity() . ' is missing key-field: "' . $keyField . '" in ' . $item->_context);
                 } elseif (isset($keys[$item->{$keyField}])) {
-                    $this->_context->logger->error('Multiple ' . $item->_identity([]) . ' with the same ' . $keyField . '="' . $item->{$keyField} . "\":\n  " . $item->_context . "\n  " . $keys[$item->{$keyField}]->_context);
+                    $this->_context->logger->error('Multiple ' . $item->identity([]) . ' with the same ' . $keyField . '="' . $item->{$keyField} . "\":\n  " . $item->_context . "\n  " . $keys[$item->{$keyField}]->_context);
                 } else {
                     $keys[$item->{$keyField}] = $item;
                 }
@@ -583,24 +583,37 @@ private static function _validate($fields, array $stack, array $skip, string $ba
     }
 
     /**
-     * Return a identity for easy debugging.
-     * Example: "@OA\Get(path="/pets")".
+     * Return a simple string representation of the annotation.
+     *
+     * @param array|null $properties the properties to include in the string representation
+     * @example "@OA\Response(response=200)"
      */
-    public function identity(): string
+    public function identity(?array $properties = null): string
     {
         $class = static::class;
-        $properties = [];
-        /** @var class-string<AbstractAnnotation> $parent */
-        foreach (static::$_parents as $parent) {
-            foreach ($parent::$_nested as $annotationClass => $entry) {
-                if ($annotationClass === $class && is_array($entry) && !Generator::isDefault($this->{$entry[1]})) {
-                    $properties[] = $entry[1];
-                    break 2;
+
+        if (null === $properties) {
+            $properties = [];
+            /** @var class-string<AbstractAnnotation> $parent */
+            foreach (static::$_parents as $parent) {
+                foreach ($parent::$_nested as $annotationClass => $entry) {
+                    if ($annotationClass === $class && is_array($entry) && !Generator::isDefault($this->{$entry[1]})) {
+                        $properties[] = $entry[1];
+                        break 2;
+                    }
                 }
             }
         }
 
-        return $this->_identity($properties);
+        $details = [];
+        foreach ($properties as $property) {
+            $value = $this->{$property};
+            if ($value !== null && !Generator::isDefault($value)) {
+                $details[] = $property . '=' . (is_string($value) ? '"' . $value . '"' : $value);
+            }
+        }
+
+        return static::shorten(static::class) . '(' . implode(',', $details) . ')';
     }
 
     /**
@@ -650,22 +663,6 @@ public function isRoot(string $rootClass): bool
         return static::class === $rootClass || $this->getRoot() === $rootClass;
     }
 
-    /**
-     * Helper for generating the identity().
-     */
-    protected function _identity(array $properties): string
-    {
-        $fields = [];
-        foreach ($properties as $property) {
-            $value = $this->{$property};
-            if ($value !== null && !Generator::isDefault($value)) {
-                $fields[] = $property . '=' . (is_string($value) ? '"' . $value . '"' : $value);
-            }
-        }
-
-        return static::shorten(static::class) . '(' . implode(',', $fields) . ')';
-    }
-
     /**
      * Validates the matching of the property value to a annotation type.
      *

src/Annotations/Operation.php

@@ -221,7 +221,7 @@ public function validate(array $stack = [], array $skip = [], string $ref = '',
         if (!Generator::isDefault($this->responses)) {
             foreach ($this->responses as $response) {
                 if (!Generator::isDefault($response->response) && $response->response !== 'default' && preg_match('/^([12345]{1}\d{2})|([12345]{1}XX)$/', (string) $response->response) === 0) {
-                    $this->_context->logger->warning('Invalid value "' . $response->response . '" for ' . $response->_identity([]) . '->response, expecting "default", a HTTP Status Code or HTTP Status Code range definition in ' . $response->_context);
+                    $this->_context->logger->warning('Invalid value "' . $response->response . '" for ' . $response->identity([]) . '->response, expecting "default", a HTTP Status Code or HTTP Status Code range definition in ' . $response->_context);
                     $valid = false;
                 }
             }

src/Annotations/Parameter.php

@@ -289,11 +289,9 @@ public function validate(array $stack = [], array $skip = [], string $ref = '',
         return $valid;
     }
 
-    /**
-     * @inheritdoc
-     */
-    public function identity(): string
+    #[\Override]
+    public function identity(?array $properties = []): string
     {
-        return parent::_identity(['name', 'in']);
+        return parent::identity(['name', 'in']);
     }
 }

tests/Annotations/AbstractAnnotationTest.php

@@ -7,6 +7,7 @@
 namespace OpenApi\Tests\Annotations;
 
 use OpenApi\Annotations as OA;
+use OpenApi\Annotations\Response;
 use OpenApi\Tests\OpenApiTestCase;
 use PHPUnit\Framework\Attributes\DataProvider;
 
@@ -142,6 +143,19 @@ public function testValidateExamples(): void
 
         $analysis->validate();
     }
+
+    public static function identityCases(): iterable
+    {
+        yield 'default' => [new Response(['response' => 200]), null, '@OA\Response(response=200)'];
+        yield '[]' => [new Response(['response' => 200]), [], '@OA\Response()'];
+        yield 'custom' => [new Response(['response' => 200]), ['response'], '@OA\Response(response=200)'];
+    }
+
+    #[DataProvider('identityCases')]
+    public function testIdentity(OA\AbstractAnnotation $annotation, ?array $identityArgs, string $expected): void
+    {
+        $this->assertSame($expected, $annotation->identity($identityArgs));
+    }
 }
 
 class SubSchema extends OA\Schema