OpenAPI 3.1 support? #373
Comments
|
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 |
For my team's use cases, you nailed the two key items on the head -- The type array could definitely be translated to an OAS 3.0 spec pretty easily, by converting it to a |
|
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! |
As noted in #373 we don't yet have support, and this should make it clearer to consumers of that.
As noted in #373 we don't yet have support, and this should make it clearer to consumers of that.
Note that, as noted in #1533, this version introduces a significant breaking changes, which requires us make code changes. The key change introduced is that we now have a `Types` type, which supports how in OpenAPI 3.1 (and JSON Schema proper) there can be multiple types. Note that we do not add the support for full OpenAPI 3.1 specifications (#373) and make sure that we only use the `.Is` call, which makes sure it's the 0th element, so we don't accidentally start to have OpenAPI 3.1 support before we're ready for it. Closes #1533.
Note that, as noted in #1533, this version introduces a significant breaking changes, which requires us make code changes. The key change introduced is that we now have a `Types` type, which supports how in OpenAPI 3.1 (and JSON Schema proper) there can be multiple types. In cases where previously we'd receive a Type of `""`, we now receive a nil array, so we need to validate that with the `.Slice()` method. Note that we do not add the support for full OpenAPI 3.1 specifications (#373) and make sure that we only use the `.Is` call, which makes sure it's the 0th element, so we don't accidentally start to have OpenAPI 3.1 support before we're ready for it. Closes #1533.
Note that, as noted in #1533, this version introduces a significant breaking changes, which requires us make code changes. The key change introduced is that we now have a `Types` type, which supports how in OpenAPI 3.1 (and JSON Schema proper) there can be multiple types. In cases where previously we'd receive a Type of `""`, we now receive a nil array, so we need to validate that with the `.Slice()` method. Note that we do not add the support for full OpenAPI 3.1 specifications (#373) and make sure that we only use the `.Is` call, which makes sure it's the 0th element, so we don't accidentally start to have OpenAPI 3.1 support before we're ready for it. Closes #1533.
|
any update for supporting openapi |
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. |
This commit ensures no Optional types are used in the FastAPI models. This change is necessary because the oapi-codegen tool (see issue [#373](oapi-codegen/oapi-codegen#373)) and Speakeasy do not yet support Optional types.
|
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 #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
(Meanwhile, I'm going to go back to maintaining gqlgen on my Sunday) 😆 |
|
Moving this comment here:
This would be great - a good balance between moving folks to 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 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 💜 |
OpenAPI 3.1 is great, brings full JSON Schema compatibility. It would be great if generator would support it.
The text was updated successfully, but these errors were encountered: