OpenAPI 3.1 support?
mitar opened this issue · 22 comments
OpenAPI 3.1 is great, brings full JSON Schema compatibility. It would be great if generator would support it.
Bumping this, OAS 3.1 was released approximately seven months ago now and brings a number of very useful features.
This would be great
So right now you can use a document with an OpenAPI 3.1 version, but we don't yet support new stuff.
There's a great post about what we need to add at https://www.openapis.org/blog/2022/05/11/openapi-v3-1-resources-for-tooling-developers
Is there anything we want to count as out of scope? I'd be tempted to look at whether I can help with the effort to add support
Related upstream issue that we'd need to wait for before we can support everything getkin/kin-openapi#230
Per getkin/kin-openapi#230 (comment), https://github.com/pb33f/libopenapi could also be a good option, but would lead to significant rework - may be worth it, especially as kin-openapi's not yet gotten around to it
Edit: maybe when it's a little more stable?
If you end up redesigning oapi-codegen using libopenapi, could you please consider allowing generating code for other languages too? I'm sure people here would be interested in using the same awesome tool to generate non-go client code
Just to cover this, there's some discussion between @deepmap-marcinr and I about this, and we're considering - for now - to convert an OpenAPI 3.1 spec to an OpenAPI 3.0 spec (via libopenapi) to continue to rely on kin-openapi, which will allow for OpenAPI 3.1 specs to continue to work, but without some of the benefits.
We'd prefer to keep on kin-openapi for the meantime, but also if there's no expected update to 3.1 (and folks do really want 3.1) we can look at shifting to use libopenapi, but it'll require a slightly more significant set of changes than we're willing to do right now, especially as Marcin is continuing to think about what a v2 could look like
For folks looking for OpenAPI 3.1 support, what features are you hoping for? We are looking at what initial changes may be required (supporting multiple types in a schema), but then wondering what additional things could be added to the backlog, like webhook support
For folks looking for OpenAPI 3.1 support, what features are you hoping for?
For my team's use cases, you nailed the two key items on the head -- type as an array, and webhooks, in that order of importance.
The type array could definitely be translated to an OAS 3.0 spec pretty easily, by converting it to a oneOf or anyOf, though nullability has some minor challenges in some cases.
The fully implemented version of OpenAPI 3.1 can be found at https://github.com/pb33f/libopenapi, while kin-openapi is still in the process of implementing it. Would switching to the former accelerate the support for OAS 3.1?
So using libopenapi is proposed in #1388 and is a good option to support OpenAPI 3.1.
It's not something I want us to switch over to as-is, as it's a significant breaking change for folks (for those using this as a library, and some behaviour changes may occur) so would assume this would be a side-by-side thing for some time before maybe switching over.
Additionally, we also need to make sure the middleware used by the project is also https://github.com/pb33f/libopenapi-validator/ instead of using kin-openapi (as they'll differ in what's supported)
I'd welcome folks trying out #1388 with their repos, making sure that it works correctly with your services, etc, and we'll hopefully get it merged before long, but I want to make sure that we set ourselves up for it well due to i.e. needing to make sure that updates to internal code for generating templates also applies to the libopenapi side of things.
It's very much something I want to get done, just also trying to balance it with several other Open Source projects I maintain (all in my free time) as well as trying to keep on top of the incoming issues and PRs!
any update for supporting openapi 3.1.0 ?
any update for supporting openapi
3.1.0?
Unfortunately not - we've got a lot of "BAU" kinda issues/PRs to look into before we can look at strategic things that will allow us to push forwards towards supporting i.e. #1388 or an alternative approach.
Sponsorship is hugely appreciated if this is blocking your organisations - and it's likely the only way we'll be able to put the time in towards it (related: #1606)
sponsoring a small monthly amount to support this
any update for supporting openapi
3.1.0?Unfortunately not - we've got a lot of "BAU" kinda issues/PRs to look into before we can look at strategic things that will allow us to push forwards towards supporting i.e. #1388 or an alternative approach.
Sponsorship is hugely appreciated if this is blocking your organisations - and it's likely the only way we'll be able to put the time in towards it (related: #1606)
sponsoring a small monthly amount to support this
Thanks Filip! We appreciate that, and you putting your money where your mouth is!
Note that the sponsorship you'd sent through is under the 1hr work/mo tier, so may not directly lead to much time we can give towards this issue, but it should help alongside other contributions / in the long run
I know it's not much but I also put in a small sponsership for this one :) Appreciate the work you guys are doing and I hope it helps a bit.
Bumping this, OAS 3.1.1 was released this October. Are there currently plans to support this?
Hey! Is there any way to follow or contribute to this work?
The update from #373 (comment) still holds true, unfortunately.
To get OpenAPI 3.1 support in oapi-codegen is a good chunk of work, in planning and making sure we're set up in a way that the maintenance burden doesn't overload us, on top of our already high support levels - it's great we're heavily used, but also involves a tonne of work!
#1388 is an option, but supporting both / migrating over is a significant chunk of work and I can't forsee being able to work on this without a significant time investment
If anyone else would like to contribute to this effort, consider getting your organization to sponsor the work, or you can personally sponsor oapi-codegen or jamietanna.
The other way to contribute to this is to take PR #1388, fork it, update it, test it out, and contribute any fixes back as another PR.
Another approach would be to either contribute code or sponsorship of fenollp for the existing upstream library kin-openapi to support OpenAPI 3.1 - see here getkin/kin-openapi#230 and specifically this comment
I have been maintaining this project for a few years now and am looking to turn this into a more sustainable initiative. Recently, I set up GitHub Sponsorship so if you'd like to support this project's future and preserve some of my mental health I encourage you to register for a monthly sponsoring here. A one-time donation can also help solve piecemeal issues.
Here's a tutorial from GitHub on how to find other maintainers that may need your help whose work you might depend on.
Regarding this specific issue, considering the large ramifications and attention to quality it entails, I would like to work on it once some funding has been promised or secured. We can discuss terms privately.
Licensing won't change due to sponsorship. All open-source work will continue to be available to all and enjoyed equally by all community members.
(Meanwhile, I'm going to go back to maintaining gqlgen on my Sunday) 😆
Moving this comment here:
Any plans to make a v3 tag with this breaking change?
This would be great - a good balance between moving folks to libopenapi while making it clear it's a breaking change.
When we performed the bump to v2 @mromaszewicz and I decided we would not support v1, especially as it was not a significantly breaking change, and in our opinion would be a fairly low effort move (as we had seen on codebases we made the changes as tests)
However, for the v3 bump - whether that's libopenapi or some of the breaking changes planned for v3 - we do not want to follow this model.
Instead, we will support v2 and v3 together, for some time I.e. 12 months. This will allow folks to move over to v3 more leisurely, while getting (at least) bug fixes.
But the problem with that, linking into #1606, is that it doubles our support burden.
We would need to now manage two sets of versions and respective maintenance. Given we're struggling to keep on top of a single version - with the sponsorship we're super appreciative of - it wouldn't be fair to us as maintainers or y'all as community to say we're going to maintain v2 and v3 together but then not set us all for success.
Trust me, I'd love to have this support in, and I'd love to say we supported OpenAPI 3.1 with all that entails - but not at the (already high) cost of maintenance.
If we're able to get significantly more sponsors and dedicate more time to bringing down the backlog of outstanding issues and getting us to a more sustainable pace, then we'd be more happy to reconsider and see if we could create a v3
Hope y'all understand 💜