Webhooks #1462

qdequippe · 2023-08-01T10:02:54Z

Version 3.1 brings "webhooks" to the specification.

qdequippe · 2023-08-01T12:35:56Z

It seems too easy ☺️ am I missing something to implement? open for feedbacks

DerManoMann · 2023-08-02T00:04:17Z

Nice one. It would be great if you could add some tests. Allowing a union of native types (string, etc) and PathItem might break things?

DerManoMann · 2023-08-02T02:26:42Z

Also, the serialize code might need to be conditional to suppress the property for 3.0.0

qdequippe · 2023-08-02T13:01:59Z

@DerManoMann I added test and changed types also for webhooks (only PathItem finally).

Also, the serialize code might need to be conditional to suppress the property for 3.0.0
tests failed due to this change, any idea on how to handle this properly?

DerManoMann

Looking good so far.

Still some way to go to make all existing tests pass, tho. Also, it would be good to ensure that webhook cannot be used with 3.0.0 - something like https://github.com/zircote/swagger-php/blob/master/src/Annotations/License.php#L77

src/Annotations/OpenApi.php

src/Attributes/OpenApi.php

DerManoMann · 2023-08-16T21:44:09Z

Sorry for ignoring this - I am quite busy ATM with paid work :/

qdequippe · 2023-08-17T05:59:48Z

Sorry for ignoring this - I am quite busy ATM with paid work :/

No problem it's normal ;) I am quite busy too, it's not critical

DerManoMann

Looking pretty good! Just a few minor things...

DerManoMann · 2023-08-18T07:43:41Z

src/Annotations/OpenApi.php

+    /**
+     * The available webhooks for the API.
+     *
+     * @var array<string,PathItem>


It might actually be nice to have a new Webhook annotation/attribute for this rather than using raw maps on top level elements.

Agree with that, I got this idea at first but I didn't know if I could add a custom annotation/attribute

Bye the way, how do you think to handle this new annotation/attribute? a new Processor BuildWebhooks?

src/Annotations/OpenApi.php

DerManoMann · 2023-08-18T07:45:15Z

src/Annotations/OpenApi.php

@@ -143,6 +150,18 @@ public function validate(array $stack = null, array $skip = null, string $ref =
            return false;
        }

+        if ($this->openapi === self::VERSION_3_0_0 && Generator::isDefault($this->paths)) {
+            $this->_context->logger->warning('The OpenAPI document must contain paths field');


nit: I'd prefer if the error messag ecould be kept the same, even if it means manually reproducing the format.

i.e. 'Required @OA\Info() not found'

DerManoMann · 2023-08-18T08:03:12Z

src/Annotations/OpenApi.php

+        }
+
+        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');


A message in similar style as above wouold be great.

Perhasps

At least one of 'Required @OA\Info(), @OA\Components() or @OA\Webhook() not found'

src/Attributes/OpenApi.php

DerManoMann

Looks promising.

A few more things:

Webhook needs to be added to the parent/nested arrays similar to other annotations in OpenApi (annotation)
The attribute version should extend the annotation version. Saves on re-declaring the properties and also allows to simplify the parent/nested relationships (which are based on annotations only)

There still needs to be code to merge the Webhook data into the right place when processing the annotation tree.
Again, this is related to $_nested. This should probably look something like this:

    public static $_nested = [
        Webhook::class => ['webhooks', 'name'],
    ];

From memory the first element in the array is the property this gets merged in and if there is a second value then that is used as propery lookup in the annotation (Webhook) to find the key to store in under.
Sounds complicated (and it kinda is, at least to understand).

DerManoMann · 2023-09-12T00:21:19Z

Examples/webhook-example/OpenApiSpec.php

+ *         version="1.0.0",
+ *         title="Webhook Example",
+ *     ),
+ *     webhooks={


This still needs updating I think?

DerManoMann · 2023-09-12T00:22:07Z

docs/reference/annotations.md

@@ -566,6 +566,8 @@ The list of values includes alternative security requirement objects that can be
 Only one of the security requirement objects need to be satisfied to authorize a request.<br />
 Individual operations can override this definition.<br />
 To make security optional, an empty security requirement `({})` can be included in the array.</p></dd>
+  <dt><strong>webhooks</strong> : <span style="font-family: monospace;">array&lt;string,PathItem|string|class-string|object&gt;</span></dt>


docs need refresh - ideally done right before merge

DerManoMann · 2023-09-12T00:23:38Z

tests/GeneratorTest.php

@@ -38,7 +38,6 @@ 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('Required @OA\Info() not found');


Hmm, this is surprising.

yceruto · 2023-09-30T22:58:18Z

src/Annotations/OpenApi.php

+        }
+
+        if ($this->openapi === self::VERSION_3_1_0 && Generator::isDefault($this->paths) && Generator::isDefault($this->webhooks) && Generator::isDefault($this->components)) {
+            $this->_context->logger->warning("At least one of 'Required @OA\Info(), @OA\Components() or @OA\Webhook() not found'");


It should be @OA\PathItem instead of @OA\Info

DerManoMann · 2023-12-11T08:34:04Z

Closing in favour of #1511.

Thanks @qdequippe for doing most of the hard work.

qdequippe · 2023-12-11T08:38:34Z

Thanks @DerManoMann for your feedbacks on this PR, sorry for the lack of time on my side.

qdequippe marked this pull request as ready for review August 1, 2023 12:33

DerManoMann requested changes Aug 3, 2023

View reviewed changes

src/Annotations/OpenApi.php Show resolved Hide resolved

src/Attributes/OpenApi.php Outdated Show resolved Hide resolved

DerManoMann requested changes Aug 18, 2023

View reviewed changes

qdequippe and others added 7 commits September 11, 2023 09:16

feat: webhooks

9b40e03

add more value type for reference object

f913b69

remove phpdoc comment

6839599

add test

54e130d

add validation based on version

1640feb

Use custom annotation/attribute for Webhook, apply reviews

860be67

add Webhook to nested type OpenAPI

e63c24e

DerManoMann requested changes Sep 12, 2023

View reviewed changes

yceruto reviewed Sep 30, 2023

View reviewed changes

DerManoMann mentioned this pull request Dec 5, 2023

Webhooks 2 #1511

Merged

DerManoMann closed this Dec 11, 2023

qdequippe deleted the webhook branch December 11, 2023 08:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Webhooks #1462

Webhooks #1462

qdequippe commented Aug 1, 2023

qdequippe commented Aug 1, 2023 •

edited

Loading

DerManoMann commented Aug 2, 2023

DerManoMann commented Aug 2, 2023

qdequippe commented Aug 2, 2023

DerManoMann left a comment

DerManoMann commented Aug 16, 2023

qdequippe commented Aug 17, 2023

DerManoMann left a comment

DerManoMann Aug 18, 2023

qdequippe Sep 11, 2023

qdequippe Sep 11, 2023

DerManoMann Aug 18, 2023

DerManoMann Aug 18, 2023

DerManoMann Aug 18, 2023

DerManoMann left a comment

DerManoMann Sep 12, 2023

DerManoMann Sep 12, 2023

DerManoMann Sep 12, 2023

yceruto Sep 30, 2023

DerManoMann commented Dec 11, 2023

qdequippe commented Dec 11, 2023

Webhooks #1462

Webhooks #1462

Conversation

qdequippe commented Aug 1, 2023

qdequippe commented Aug 1, 2023 • edited Loading

DerManoMann commented Aug 2, 2023

DerManoMann commented Aug 2, 2023

qdequippe commented Aug 2, 2023

DerManoMann left a comment

Choose a reason for hiding this comment

DerManoMann commented Aug 16, 2023

qdequippe commented Aug 17, 2023

DerManoMann left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DerManoMann left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DerManoMann commented Dec 11, 2023

qdequippe commented Dec 11, 2023

qdequippe commented Aug 1, 2023 •

edited

Loading