search

cebe / php-openapi

Read and write OpenAPI yaml/json files and make the content accessible in PHP objects.
MIT License
466 stars 87 forks source link

Draft: OpenAPI 3.1 #128

Open cebe opened 2 years ago

cebe commented 2 years ago

This branch will contain all changes made to support OpenAPI 3.1.

I added the following:

Possibly incomplete list of TODOs on this one:

This replaces #117.

Jean85 commented 2 years ago

This looks great, thank you @cebe! Can we help in any way? Is there a "TODO" list to complete this?

cebe commented 2 years ago

Is there a "TODO" list to complete this?

Added a TODO list to the main comment on this PR. not sure if this is all that needs to be done though.

colinmollenhour commented 2 years ago

Has anyone done much testing with this PR? Perhaps if you are using it successfully and share your experiences it will help push it closer to merge time.

I'm really looking forward to using this with the PHP League OpenAPI validator!

colinmollenhour commented 2 years ago

Is it actually possible to support OpenAPI 3.1 until the underlying justinrainbow/json-schema library support JSON Schema Draft 2020-12?

For example, one new feature of OpenAPI 3.1 not mentioned on #101 is the new unevaluatedProperties option, but this is really just a new feature of JSON Schema. I'm not sure if that needs to be implemented specifically in this library or not, but I would assume it at least needs to be supported by the JSON Schema parser?

philsturgeon commented 2 years ago

If you released a new version with OAS3.1 support and didn't support unevaluatedProperties properties straight away then I doubt anyone would even notice. I wouldn't let that hold you up.

Switching away from hustinrainbow/json-schema might be on the cards. It seems like development has slowed down (https://github.com/justinrainbow/json-schema/issues/658) and its mostly just in maintenance now.

This was suggested as a supposedly drop-in replacement: https://opis.io/json-schema

It might be you can just swap packages and get a lot of the way there on the OAS3.1 schema differences.

shulard commented 1 year ago

Hello guys !

How can we help here ? Do you need more tests or is this PR miss some code ?

philsturgeon commented 1 year ago

@cebe I completely understand how busy you are, but if you ever want to chat about any of this I would be happy to hop on a Zoom call. Poke me on DMs somewhere and I'll send you a schedule link. No pressure, just want to unblock if I can.

WyriHaximus commented 1 year ago

@cebe Is there a way I can help move this forward? What mainly brought me here today is PHP 8.2 deprecations so I'll look into fixing those on the 3.1 and default branches. Aside from that, I've been using that branch for months now to generate an API client without any issue with a 3.1 spec so far. From my experience, it's pretty stable in its current state.

WyriHaximus commented 1 year ago

The 8.2 deprecations pr for OA 3.1: https://github.com/cebe/php-openapi/pull/178

WyriHaximus commented 1 year ago

Also just filed https://github.com/cebe/php-openapi/pull/179 with a small fix for webhooks

DEVizzent commented 1 year ago

@cebe I also was doing some test with this branch and really good results. If you need some help to finish some stuff before merge, I can help. Thank for fixing the deprecations @WyriHaximus

acelaya commented 1 year ago

@DEVizzent I came across your fork when searching for OAS 3.1 support in this library.

Considering it's now even used by one of thephpleague packages, should we consider it now "the official" one? And if so, would you be open to enable issues on your fork? I would like to report something that works when using OAS 3.0 but not OAS 3.1

DEVizzent commented 1 year ago

@DEVizzent I came across your fork when searching for OAS 3.1 support in this library.

Considering it's now even used by one of thephpleague packages, should we consider it now "the official" one? And if so, would you be open to enable issues on your fork? I would like to report something that works when using OAS 3.0 but not OAS 3.1

I don't know if official one. But here we didn't find a way to contribute and we need keep evolving the library. So, feel free to create a ticket in the fork and contribute to the project. I will help if I can.

acelaya commented 1 year ago

I don't know if official one. But here we didn't find a way to contribute and we need keep evolving the library. So, feel free to create a ticket in the fork and contribute to the project. I will help if I can.

I would love to, but my point was that issues are disabled there 😅

image

To enable issues you need to go to https://github.com/DEVizzent/cebe-php-openapi/settings, and check this:

image

shulard commented 1 year ago

Maybe someone else already though about it but if @cebe can't maintain this package anymore, based on this MR discussion, it can be interesting to avoid using a personal namespace (a bit too late here because of thephpleague adoption :smile:).

It might be a requirement to have at least two persons involved in the fork (I don't know @DEVizzent if you already gave access to some other people…) to avoid a blocked situation like this. Same for packagist "distribution channel", if we all decide to move from this current package, no-one can mark it "abandoned" to help user migrate.

Not sure it's relevant today but to prevent that kind of situation in the future, having "a team" behind the code seems important.

DEVizzent commented 1 year ago

I don't know if official one. But here we didn't find a way to contribute and we need keep evolving the library. So, feel free to create a ticket in the fork and contribute to the project. I will help if I can.

I would love to, but my point was that issues are disabled there 😅

image

To enable issues you need to go to https://github.com/DEVizzent/cebe-php-openapi/settings, and check this:

image

Sorry I thought it was a default option. Now it's enabled.

DEVizzent commented 1 year ago

Maybe someone else already though about it but if @cebe can't maintain this package anymore, based on this MR discussion, it can be interesting to avoid using a personal namespace (a bit too late here because of thephpleague adoption 😄).

It might be a requirement to have at least two persons involved in the fork (I don't know @DEVizzent if you already gave access to some other people…) to avoid a blocked situation like this. Same for packagist "distribution channel", if we all decide to move from this current package, no-one can mark it "abandoned" to help user migrate.

Not sure it's relevant today but to prevent that kind of situation in the future, having "a team" behind the code seems important.

I agree. WyriHaximus is also a collaborator in the project. And if there are other people who participate on it, I think it's healthy share this permissions.