CLI-based code generators working from OpenAPI specs

[arhimede]

this is a 2 tasks ticket

1. implement OpenApi
2. based on OpenAPi docs , the CLI will generate the necessary code

https://laminas.slack.com/archives/C011F9W87E1/p1667849786650579?thread_ts=1667849649.469589&cid=C011F9W87E1

[arhimede]

the creation of the documentation – I would have expected the new OpenAPI specifications here and not a commercial product

[arhimede]

https://learn.openapis.org/

[arhimede]

https://github.com/Redocly/redoc?tab=readme-ov-file

generate documentation from OpenAPI

[arhimede]

https://apisyouwonthate.com/blog/documenting-php-apis-with-openapi/

[alexmerlin]

https://apisyouwonthate.com/blog/documenting-php-apis-with-openapi/

This guide will cover using Swagger-PHP you can do this with old-school “docblock” style code comments, or PHP 8+ users can use the newer Annotations approach...

I see that we're not alone having issues distinguishing annotations vs attributes. 😁

[alexmerlin]

@arhimede

Note: The handler for /security/generate-token and /security/refresh-token endpoints is in vendor.

vendor/mezzio/mezzio-authentication-oauth2/src/TokenEndpointHandler.php

so I cannot directly attach OpenAPI attributes to the class itself.

So, I came up with the idea that I store them in src/App/src/RoutesDelegator.php where App module's routes are defined.

From here came the idea:

What if we use the RoutesDelegators to store the OpenAPI attributes?

This was we would not 'pollute' the handlers with tons of "comments". Like, each module's RoutesDelegator would store the OpenAPI definitions for all the endpoints found in that specific module.

Note: This would make these RoutesDelegators pretty large, but we do not have to touch those too often.

[arhimede]

what if we store the OpenAPI attributes directly in

vendor/mezzio/mezzio-authentication-oauth2/src/TokenEndpointHandler.php

https://github.com/mezzio/mezzio-authentication-oauth2

[arhimede]

Also storing in RoutesDelegator those comments is a good idea At least will have direct control over it withou tthe need to do a separate release for mezzio/mezzio-authentication-oauth2

[alexmerlin]

what if we store the OpenAPI attributes directly in

vendor/mezzio/mezzio-authentication-oauth2/src/TokenEndpointHandler.php

https://github.com/mezzio/mezzio-authentication-oauth2

Why/How would we do that? We do not touch stuff found in vendor.

For TokenEndpointHandler we need to either use the RoutesDelegator solution or - as @MarioRadu suggested - make our own TokenEndpointHandler which extends vendor/mezzio/mezzio-authentication-oauth2/src/TokenEndpointHandler.php