Initial attempt at adding Swagger annotations#204
Conversation
| namespace Piwik\Plugins\CustomAlerts; | ||
|
|
||
| use Exception; | ||
| use OpenApi\Annotations as OA; |
There was a problem hiding this comment.
This isn't technically required for the documentation to be generated, but it's nice for autocomplete.
|
@AltamashShaikh @james-hill-matomo Can you please take an initial look at this and let me know what you think? |
AltamashShaikh
left a comment
AltamashShaikh
left a comment
There was a problem hiding this comment.
@snake14 Good work
I see errors when I paste the JSON
Also not important, we should make this screen better if possible
|
@snake14 Overall looks good to me |
Yeah. I forgot to mention that. I did what the openmost swagger plugin does and included the method query parameter in the paths. This is necessary to keep the paths unique, since without the query parameters, all paths are
UI was completely out of scope for this ticket. I was simply using editor.swagger.io so that I could compare the presentation to the openmost swagger plugin UI. That said, it's displaying the necessary data about the |
| * | ||
| * @method static \Piwik\Plugins\CustomAlerts\API getInstance() | ||
| * | ||
| * @OA\Schema( |
There was a problem hiding this comment.
It would be really nice if we could define the schema as part of a DTO or at least the model similar to this example.
There was a problem hiding this comment.
Agree - I'm not sure where you're linking to, but I'd love to have response objects (and possibly input data objects) defined as their own classes and re-used. RESTy.
We don't have the budget to big bang upgrade everything, but moving in that direction makes sense to me.
There was a problem hiding this comment.
That's annoying that the link didn't work. I was linking to https://zircote.github.io/swagger-php/guide/examples.html#product-php, but had the Annotation option selected.
|
Closing in favour of #205 |
3 participants
Description
POC adding annotations for php-swagger.
If you check out this branch and the new plugin PR, you can test generating the documentation by running the following console command:
openapidocs:generate-doc-file --plugin=CustomAlerts. I have been pasting that output into https://editor.swagger.io/ to view how it presents.