OpenAPI 3.1 support?
mitar opened this issue · 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!