search

dotkernel / api

DotKernel's PSR-7 REST style API built around the Mezzio API skeleton.
https://docs.dotkernel.org/api-documentation/
MIT License
28 stars 4 forks source link

CLI-based code generators working from OpenAPI specs #168

Open arhimede opened 1 year ago

arhimede commented 1 year ago

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 commented 1 month ago

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

arhimede commented 1 month ago

https://learn.openapis.org/

arhimede commented 1 month ago

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

generate documentation from OpenAPI

arhimede commented 1 month ago

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

alexmerlin commented 1 month ago

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 commented 5 days ago

@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 commented 5 days ago

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 commented 5 days ago

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 commented 5 days ago

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