From 860be67205be58bd5750d7df97a056c408819174 Mon Sep 17 00:00:00 2001 From: Quentin Dequippe Date: Mon, 11 Sep 2023 09:51:32 +0400 Subject: [PATCH] Use custom annotation/attribute for Webhook, apply reviews --- src/Annotations/OpenApi.php | 6 +++--- src/Annotations/Webhook.php | 25 +++++++++++++++++++++++ src/Attributes/OpenApi.php | 13 ++++++------ src/Attributes/Webhook.php | 34 +++++++++++++++++++++++++++++++ src/Serializer.php | 1 + tests/Annotations/OpenApiTest.php | 4 ++-- tests/ContextTest.php | 2 +- tests/GeneratorTest.php | 2 +- 8 files changed, 73 insertions(+), 14 deletions(-) create mode 100644 src/Annotations/Webhook.php create mode 100644 src/Attributes/Webhook.php diff --git a/src/Annotations/OpenApi.php b/src/Annotations/OpenApi.php index 32cfdf48..0be0cd72 100644 --- a/src/Annotations/OpenApi.php +++ b/src/Annotations/OpenApi.php @@ -101,7 +101,7 @@ class OpenApi extends AbstractAnnotation /** * The available webhooks for the API. * - * @var array + * @var Webhook[] */ public $webhooks = Generator::UNDEFINED; @@ -151,13 +151,13 @@ public function validate(array $stack = null, array $skip = null, string $ref = } if ($this->openapi === self::VERSION_3_0_0 && Generator::isDefault($this->paths)) { - $this->_context->logger->warning('The OpenAPI document must contain paths field'); + $this->_context->logger->warning('Required @OA\PathItem() not found'); return false; } if ($this->openapi === self::VERSION_3_1_0 && Generator::isDefault($this->paths) && Generator::isDefault($this->webhooks) && Generator::isDefault($this->components)) { - $this->_context->logger->warning('The OpenAPI document must contain at least one paths field, a components field or a webhooks field'); + $this->_context->logger->warning("At least one of 'Required @OA\Info(), @OA\Components() or @OA\Webhook() not found'"); return false; } diff --git a/src/Annotations/Webhook.php b/src/Annotations/Webhook.php new file mode 100644 index 00000000..4fb581f0 --- /dev/null +++ b/src/Annotations/Webhook.php @@ -0,0 +1,25 @@ +|null $webhooks - * @param array|null $x - * @param Attachable[]|null $attachables + * @param Server[]|null $servers + * @param Tag[]|null $tags + * @param PathItem[]|null $paths + * @param Webhook[]|null $webhooks + * @param array|null $x + * @param Attachable[]|null $attachables */ public function __construct( string $openapi = self::DEFAULT_VERSION, diff --git a/src/Attributes/Webhook.php b/src/Attributes/Webhook.php new file mode 100644 index 00000000..777ad2f0 --- /dev/null +++ b/src/Attributes/Webhook.php @@ -0,0 +1,34 @@ +|null $x + * @param Attachable[]|null $attachables + */ + public function __construct( + ?string $name = null, + ?PathItem $pathItem = null, + // annotation + ?array $x = null, + ?array $attachables = null + ) { + parent::__construct([ + 'name' => $name ?? Generator::UNDEFINED, + 'pathItem' => $pathItem ?? Generator::UNDEFINED, + 'x' => $x ?? Generator::UNDEFINED, + 'value' => $this->combine($name, $pathItem, $attachables), + ]); + } +} diff --git a/src/Serializer.php b/src/Serializer.php index 71f9b2b9..d8b59d35 100644 --- a/src/Serializer.php +++ b/src/Serializer.php @@ -58,6 +58,7 @@ class Serializer OA\Trace::class, OA\Xml::class, OA\XmlContent::class, + OA\Webhook::class, ]; protected static function isValidAnnotationClass(string $className): bool diff --git a/tests/Annotations/OpenApiTest.php b/tests/Annotations/OpenApiTest.php index 33e48a17..95458d90 100644 --- a/tests/Annotations/OpenApiTest.php +++ b/tests/Annotations/OpenApiTest.php @@ -13,7 +13,7 @@ class OpenApiTest extends OpenApiTestCase { public function testValidVersion310(): void { - $this->assertOpenApiLogEntryContains('The OpenAPI document must contain at least one paths field, a components field or a webhooks field'); + $this->assertOpenApiLogEntryContains("At least one of 'Required @OA\Info(), @OA\Components() or @OA\Webhook() not found'"); $openapi = new OA\OpenApi(['_context' => $this->getContext()]); $openapi->openapi = '3.1.0'; @@ -22,7 +22,7 @@ public function testValidVersion310(): void public function testValidVersion300(): void { - $this->assertOpenApiLogEntryContains('The OpenAPI document must contain paths field'); + $this->assertOpenApiLogEntryContains('Required @OA\PathItem() not found'); $openapi = new OA\OpenApi(['_context' => $this->getContext()]); $openapi->openapi = '3.0.0'; diff --git a/tests/ContextTest.php b/tests/ContextTest.php index d6e3cea8..4604b867 100644 --- a/tests/ContextTest.php +++ b/tests/ContextTest.php @@ -26,7 +26,7 @@ public function testDetect(): void public function testFullyQualifiedName(): void { - $this->assertOpenApiLogEntryContains('The OpenAPI document must contain paths field'); + $this->assertOpenApiLogEntryContains('Required @OA\PathItem() not found'); $openapi = (new Generator($this->getTrackingLogger())) ->setAnalyser(new TokenAnalyser()) ->generate([$this->fixture('Customer.php')]); diff --git a/tests/GeneratorTest.php b/tests/GeneratorTest.php index 3853cbad..4cdc653b 100644 --- a/tests/GeneratorTest.php +++ b/tests/GeneratorTest.php @@ -38,7 +38,7 @@ public function testScan(string $sourceDir, iterable $sources): void public function testScanInvalidSource(): void { $this->assertOpenApiLogEntryContains('Skipping invalid source: /tmp/__swagger_php_does_not_exist__'); - $this->assertOpenApiLogEntryContains('The OpenAPI document must contain paths field'); + $this->assertOpenApiLogEntryContains('Required @OA\PathItem() not found'); (new Generator($this->getTrackingLogger())) ->setAnalyser($this->getAnalyzer())