You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Reacted by Marques Johansson, Elmer Thomas, Jennifer Mah, Alvise, Lukáš Kováč, Jarod Burchill, Florian BRUNIAUX, Antoine Sauray, Marco, Jacob Barnett and 158 more
Reacted by Marco, Jacob Barnett, Dimitris Moraitis, Phillip Verheyden, Sławomir Ehlert, Šimon Demočko, Wouter Boereboom, Jordi Burgos, Niels ten Boom, Martin Collado and 10 more
Reacted by Hilário Coelho, Moyo George, Sasha Hilton, Yunhao Cao, Niccolò Belli, Thomas Koppensteiner, Florian Häser, Jorge Rodríguez Pedrianes, Jay Ahn, Bořek Leikep and 7 more
Reacted by Hilário Coelho, Jon-Håkon Bøe Røli, Moyo George, childish-sambino, Grant Lucas, Yunhao Cao, Thomas, Bruce Felt, Jorge Rodríguez Pedrianes, Jay Ahn and 7 more
Reacted by Chao Yang, Bořek Leikep, Denis Golubovic, Jon-Håkon Bøe Røli, bonukai, Jorge Rodríguez Pedrianes, Niccolò Belli, Eric Durand-Tremblay, T. Franzel, Thomas and 17 more
This is a big oof on my part. I just spent a ton of time setting up an API spec for a client and used 3.1.0 and now that its all approved I need to actually program the API server and need to generate the base files from the spec. Now I find out that not only does this package not support 3.1.0 currently but I cannot seem to find any code generator that does :( big yikes! I have to figure out what my options are at this point as my spec currently makes heavy use of the type as an array not a string and I also use oneOf with "null" or a $ref throughout the whole thing which makes it a major problem to downgrade to 3.0.3 at this point.
I see that as of 27 days ago at the time of me writing this, the 3.1 spec was added to swagger-api/swagger-parser#1535 - Does anyone have any idea when there will be a beta / snapshot release that will support 3.1.0 as if its going to be soon(tm), I might keep just waiting for that as an option before nuking my 3.1.0 setup....
Reacted by Max, mc_fish, Jonas Strassel, Simon Mikkelsen, Steph Ahart, Jason Hoetger, G, Matthew Edwards, Nicolas Dréno, Kir and 4 more
We are also waiting for this feature, to generate classes from components if there is no API (e. g. publish Kafka Event Objects as Open Api Spec). I hope there will be soon a new release for that.
Reacted by Ivan, wrightsonm, Max, mc_fish, Emanuele Saccomandi, slPerryRhodan, Kir, Igor Filipenko and Kernevez
Reacted by Thomas Koppensteiner, Bořek Leikep, jemanimtim, DieterPeters, Victoria Martin, Max, mc_fish, Emanuele Saccomandi, Reuben Tunguia, slPerryRhodan and 7 more
This is a big oof on my part. I just spent a ton of time setting up an API spec for a client and used 3.1.0 and now that its all approved I need to actually program the API server and need to generate the base files from the spec. Now I find out that not only does this package not support 3.1.0 currently but I cannot seem to find any code generator that does :( big yikes! I have to figure out what my options are at this point as my spec currently makes heavy use of the type as an array not a string and I also use oneOf with "null" or a $ref throughout the whole thing which makes it a major problem to downgrade to 3.0.3 at this point.
I see that as of 27 days ago at the time of me writing this, the 3.1 spec was added to swagger-api/swagger-parser#1535 - Does anyone have any idea when there will be a beta / snapshot release that will support 3.1.0 as if its going to be soon(tm), I might keep just waiting for that as an option before nuking my 3.1.0 setup....
Type null works with 3.0.3 specs and our tool
Type arrays can be converted to oneOf with each type in a different schema.
Hello! As the maintainer of openapi.tools, and as somebody works with Linux Foundation helping out in OpenAPI-land, I'm reaching out to tooling vendors to track the progress towards supporting OpenAPI v3.1, to see what roadblocks there are beyond folks just generally being busy at this ridiculous time.
OpenAPI v3.1 has a bunch of great little changes, solving problems like the JSON Schema <!=> OpenAPI Schema Object divergence. It also fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, but we need tooling to catch up. Just in case folks didn't notice, or don't have resources to simplify the process, I'm here to give a friendly prod and send over some handy links.
Here are a few articles showing off the differences between OpenAPI v3.0 and v3.1.
No rush, but when you're starting work on it, please update this issue so I can update openapi.tools to reflect that, and folks will have a way to subscribe for updates.
LMK if you have any questions!
Reacted by Thomas Koppensteiner, Tobi, Steven Altsman, Maksim Zvankovich, Travis Tripp, slPerryRhodan, plondino, Thomas Peter Berntsen, Mario Toffia, Thomas Schaffter and 14 more
Hi @bgalek we haven't found any relevant (complete) support nor (REAL) market adoption of OpenAPI 3.1 (I guess due is a wrong minor version, there are huge breaking changes and it should be a major version instead (among other potential reasons))
So what would be the point to move "official" support to OpenAPI 3.1? Wouldn't it be better to wait for a proper and fixed major version (maybe OpenAPI 4.x)? And keep for the time being the "official" support to OpenAPI 3.0.x
I've asked a few communities, and people do tend to miss some features in 3.0 (that were introduced to 3.1) like the major one I've described here: springdoc/springdoc-openapi#2765 (comment)
After openapi@4 is published, tools will need to adjust and release new versions. That will take time, and it doesn't mean that 3.1 should not be supported, either.
So, supporting 3.1 and then supporting upcoming 4 are separate tasks ;)
Supporting 3.1 I think will a be waste of resources that should be focused in any pending improvements in 3.0 support in all the related tools (OpenAPI generator, springdoc, etc.) and to speed up 4.0 support and adoption when it was released in the short future.
I think that concentrating the effort will be more positive than to disperse it in versions that were wrong from the inception (3.1). To disperse the effort could lead to a less-than-optimal support in valuable versions that deserve the resource assignation.
Reacted by Marcel Stör and Fernando Blanch Calvete
Version 3.1 addresses several baffling defects in version 3.0 that cripple OAS for its intended purpose: documenting APIs. It has been the current version for years now.
One of the most significant fixes in 3.1 is the ability to provide a description alongside any use of a reference (model). This is critical in documenting an API, yet is inexplicably prohibited pre-3.1.
For example: I have a model that represents an integer-based setting on a piece of equipment. There will be dozens or more such settings in a complex API, all of them meaning something different. In every case, I need to describe what one particular integer-based setting is used for, as opposed to some other integer-based setting. Maybe I have one called "Volume" and another one called "Offset" and another called "Tap count." Every one of those is an Integer_setting. How can you document an API without describing each use of its structures?
One can think of endless examples. What about an API that had something to do with surveying or farming, where you needed to work with rectangular land parcels. You might have a model called Rect, referred-to all over the place. What does this Rect mean as opposed to that one? You need to be able to attach a description to each appearance of Rect in the API.
Versions before 3.1 are crippled by this and other design problems. What problems are people calling out in 3.1?
To continue to let tools languish, unusable, for many purposes until a nebulous version 4 appears... and for several more years after that until tools actually support it... seems absurd. You might as well just call OpenAPI a wrap and move on to something else.
Reacted by ziyuang, Jean Revertera and Andy Fink-Miller
There is definitely support for OpenAPI 3.1 in tools, and we are starting to see more 3.1 descriptions in the wild. You can see a list here https://openapi.tools/ of tools that declare they support 3.1. It does take a long time for new versions of specifications to take hold. We saw this in the 2.0 -> 3.0 transition.
Adding 3.1 support for code generators is harder than it is for most tooling because 3.1 opened the doors to a range of different capabilities in JSON Schema 2020-12.
@juliojgd It is certainly debatable as to whether 3.1 should have been 4.0. And certainly to some implementors it feels that way. However, to authors of API Descriptions the changes are 98% additive and not breaking. The decision was hotly debated and it came down to a vote. So, be assured that if you think it should have been 4.0, there are some members of the OpenAPI technical steering committee that agree with you.
But here we are with a 3.1 that is easy for some to support and hard for others. But it is an important step to make, and one that needed to be made. For those saying you should wait for 4.0. I wouldn't recommend that. 4.0 will be a major update and as we have explored the features we want to bring, we have identified that many of the improvements would not be breaking. So, rather than make people wait, for those enhancements, we will be continuing the 3.x line while working on the 4.0 release. There will be a 3.2 release "fairly soon" that will add some simple to add features that should be easy to support. However, we currently are planning a 3.3. release to follow to backport some of the ideas we came up with for moonwalk (4.0).
While this may seem like a lot of work to do for a group that hasn't released a new version in 3 years, we have recently grown the technical steering committee, and there is lots of new life in the group.
@Stokestack I'm glad you like the ability to add description and summary alongside $refs. This previous constraint wasn't a decision made the OpenAPI group. It was a constraint of earlier versions of JSON Schemas because the semantics of merging keywords was not clearly defined. By adopting JSON Schema 2020-12, were able to leverage this work and start bringing peer keywords. We only started with "description" and "summary" because we knew they were safe. If there are other keywords that you believe would be valuable to sit alongside a $ref, let us know by creating an issue in the OpenAPI specification repo.
Reacted by Thomas Schaffter, G, Bartosz Gałek and verglor
@darrelmiller Thanks for that response. I don't understand how JSON Schema precluded anything, but I haven't studied it. But I didn't think OAS 3 was JSON-Schema-compliant anyway, so I'm perplexed as to why it would be constrained by failings of that standard.
I will keep your suggestion in mind about filing issues on other keywords.
In my opinion some reasons why we don't have more 3.1 tooling here is because
users ask for it but few are willing to help us build it (here and another project)
users who did build it here (me) had their work deleted from this repo
I was a python team and core team contributor to this repo until they required that I remove my generator from this project. The python generator that I built strove to more fully conform to 3.0.3 and 3.1.0 requirements including running json schema unit tests. If you check my PRs here I added a ton of json schema data to our Java layer and implemented the features in Python. With my code not being wanted here, I hosted it in a new project https://github.com/openapi-json-schema-tools/openapi-json-schema-generator where I saw some adoption but not many contributors over two years. For those reasons I have stopped building my project.
For general feedback on OpenAPI specification, please open an issue in the official repo as this project is not affiliated with OpenAPI Initiative (OAI).
Activity
spacether commentedon Apr 13, 2021
We use swagger-parser to parse openapi specs. That project must implement v 3.1 spec parsing before we can implement it in the generators.
Revert "Our policies state:"
darkbasic commentedon Sep 10, 2021
https://github.com/swagger-api/swagger-parser/commits/oas3.1
cgfarmer4 commentedon May 11, 2022
Any updates to share on potentially updating the generators to OAS 3.1?
gunsluo commentedon May 15, 2022
swagger-api/swagger-parser#1535, there has been no update for half a year.
cyangle commentedon May 27, 2022
OAS 3.1 support has been added to swagger-parser in swagger-api/swagger-parser#1730
denisgolubovic commentedon Jun 13, 2022
What release do you aim for this to be implemented in the generator? 6.1.0?
kiwisincebirth commentedon Jun 16, 2022
swagger-parser 2.1 has been released with OAS 3.1 support
https://github.com/swagger-api/swagger-parser/releases/tag/v2.1.0
RickKukiela commentedon Jun 22, 2022
This is a big oof on my part. I just spent a ton of time setting up an API spec for a client and used 3.1.0 and now that its all approved I need to actually program the API server and need to generate the base files from the spec. Now I find out that not only does this package not support 3.1.0 currently but I cannot seem to find any code generator that does :( big yikes! I have to figure out what my options are at this point as my spec currently makes heavy use of the
typeas anarraynot astringand I also useoneOfwith"null"or a$refthroughout the whole thing which makes it a major problem to downgrade to3.0.3at this point.I see that as of
27 days agoat the time of me writing this, the 3.1 spec was added to swagger-api/swagger-parser#1535 - Does anyone have any idea when there will be a beta / snapshot release that will support 3.1.0 as if its going to be soon(tm), I might keep just waiting for that as an option before nuking my 3.1.0 setup....slPerryRhodan commentedon Jun 23, 2022
We are also waiting for this feature, to generate classes from components if there is no API (e. g. publish Kafka Event Objects as Open Api Spec). I hope there will be soon a new release for that.
tobq commentedon Jul 6, 2022
Any updates on 3.1 support?
Stokestack commentedon Jul 15, 2022
This is a huge impediment. I too have an API that relies on 3.1 features. It seems to be taking the toolchain a very long time to support it.
spacether commentedon Jul 15, 2022
Type null works with 3.0.3 specs and our tool
Type arrays can be converted to oneOf with each type in a different schema.
philsturgeon commentedon Jul 18, 2022
Hello! As the maintainer of openapi.tools, and as somebody works with Linux Foundation helping out in OpenAPI-land, I'm reaching out to tooling vendors to track the progress towards supporting OpenAPI v3.1, to see what roadblocks there are beyond folks just generally being busy at this ridiculous time.
OpenAPI v3.1 has a bunch of great little changes, solving problems like the JSON Schema <!=> OpenAPI Schema Object divergence. It also fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, but we need tooling to catch up. Just in case folks didn't notice, or don't have resources to simplify the process, I'm here to give a friendly prod and send over some handy links.
Here are a few articles showing off the differences between OpenAPI v3.0 and v3.1.
Here are some example files which can make for handy pass/fail test cases:
https://github.com/Mermade/openapi3-examples/tree/master/3.1
If you're looking for the JSON Schema that defines a valid OpenAPI document, that'll be right over here:
https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1
No rush, but when you're starting work on it, please update this issue so I can update openapi.tools to reflect that, and folks will have a way to subscribe for updates.
LMK if you have any questions!
43 remaining items
Haarolean commentedon Aug 11, 2024
@wing328 what's the process of reporting issues encountered while building 3.1 specs? Should I raise a separate issue or sth else?
wing328 commentedon Aug 21, 2024
yes please
bgalek commentedon Nov 29, 2024
Check out this poll: springdoc/springdoc-openapi#2790
I hope 3.1 will be default there, so this feature will be much appreciated ;)
juliojgd commentedon Nov 29, 2024
Hi @bgalek we haven't found any relevant (complete) support nor (REAL) market adoption of OpenAPI 3.1 (I guess due is a wrong minor version, there are huge breaking changes and it should be a major version instead (among other potential reasons))
So what would be the point to move "official" support to OpenAPI 3.1? Wouldn't it be better to wait for a proper and fixed major version (maybe OpenAPI 4.x)? And keep for the time being the "official" support to OpenAPI 3.0.x
bgalek commentedon Nov 29, 2024
I've asked a few communities, and people do tend to miss some features in 3.0 (that were introduced to 3.1) like the major one I've described here: springdoc/springdoc-openapi#2765 (comment)
After openapi@4 is published, tools will need to adjust and release new versions. That will take time, and it doesn't mean that 3.1 should not be supported, either.
So, supporting 3.1 and then supporting upcoming 4 are separate tasks ;)
juliojgd commentedon Nov 29, 2024
Supporting 3.1 I think will a be waste of resources that should be focused in any pending improvements in 3.0 support in all the related tools (OpenAPI generator, springdoc, etc.) and to speed up 4.0 support and adoption when it was released in the short future.
I think that concentrating the effort will be more positive than to disperse it in versions that were wrong from the inception (3.1). To disperse the effort could lead to a less-than-optimal support in valuable versions that deserve the resource assignation.
Stokestack commentedon Nov 29, 2024
Version 3.1 addresses several baffling defects in version 3.0 that cripple OAS for its intended purpose: documenting APIs. It has been the current version for years now.
One of the most significant fixes in 3.1 is the ability to provide a description alongside any use of a reference (model). This is critical in documenting an API, yet is inexplicably prohibited pre-3.1.
For example: I have a model that represents an integer-based setting on a piece of equipment. There will be dozens or more such settings in a complex API, all of them meaning something different. In every case, I need to describe what one particular integer-based setting is used for, as opposed to some other integer-based setting. Maybe I have one called "Volume" and another one called "Offset" and another called "Tap count." Every one of those is an Integer_setting. How can you document an API without describing each use of its structures?
One can think of endless examples. What about an API that had something to do with surveying or farming, where you needed to work with rectangular land parcels. You might have a model called Rect, referred-to all over the place. What does this Rect mean as opposed to that one? You need to be able to attach a description to each appearance of Rect in the API.
Versions before 3.1 are crippled by this and other design problems. What problems are people calling out in 3.1?
To continue to let tools languish, unusable, for many purposes until a nebulous version 4 appears... and for several more years after that until tools actually support it... seems absurd. You might as well just call OpenAPI a wrap and move on to something else.
darrelmiller commentedon Nov 30, 2024
There is definitely support for OpenAPI 3.1 in tools, and we are starting to see more 3.1 descriptions in the wild. You can see a list here https://openapi.tools/ of tools that declare they support 3.1. It does take a long time for new versions of specifications to take hold. We saw this in the 2.0 -> 3.0 transition.
Adding 3.1 support for code generators is harder than it is for most tooling because 3.1 opened the doors to a range of different capabilities in JSON Schema 2020-12.
@juliojgd It is certainly debatable as to whether 3.1 should have been 4.0. And certainly to some implementors it feels that way. However, to authors of API Descriptions the changes are 98% additive and not breaking. The decision was hotly debated and it came down to a vote. So, be assured that if you think it should have been 4.0, there are some members of the OpenAPI technical steering committee that agree with you.
But here we are with a 3.1 that is easy for some to support and hard for others. But it is an important step to make, and one that needed to be made. For those saying you should wait for 4.0. I wouldn't recommend that. 4.0 will be a major update and as we have explored the features we want to bring, we have identified that many of the improvements would not be breaking. So, rather than make people wait, for those enhancements, we will be continuing the 3.x line while working on the 4.0 release. There will be a 3.2 release "fairly soon" that will add some simple to add features that should be easy to support. However, we currently are planning a 3.3. release to follow to backport some of the ideas we came up with for moonwalk (4.0).
While this may seem like a lot of work to do for a group that hasn't released a new version in 3 years, we have recently grown the technical steering committee, and there is lots of new life in the group.
@Stokestack I'm glad you like the ability to add description and summary alongside $refs. This previous constraint wasn't a decision made the OpenAPI group. It was a constraint of earlier versions of JSON Schemas because the semantics of merging keywords was not clearly defined. By adopting JSON Schema 2020-12, were able to leverage this work and start bringing peer keywords. We only started with "description" and "summary" because we knew they were safe. If there are other keywords that you believe would be valuable to sit alongside a $ref, let us know by creating an issue in the OpenAPI specification repo.
Stokestack commentedon Nov 30, 2024
@darrelmiller Thanks for that response. I don't understand how JSON Schema precluded anything, but I haven't studied it. But I didn't think OAS 3 was JSON-Schema-compliant anyway, so I'm perplexed as to why it would be constrained by failings of that standard.
I will keep your suggestion in mind about filing issues on other keywords.
spacether commentedon Nov 30, 2024
In my opinion some reasons why we don't have more 3.1 tooling here is because
I was a python team and core team contributor to this repo until they required that I remove my generator from this project. The python generator that I built strove to more fully conform to 3.0.3 and 3.1.0 requirements including running json schema unit tests. If you check my PRs here I added a ton of json schema data to our Java layer and implemented the features in Python. With my code not being wanted here, I hosted it in a new project https://github.com/openapi-json-schema-tools/openapi-json-schema-generator where I saw some adoption but not many contributors over two years. For those reasons I have stopped building my project.
wing328 commentedon Nov 30, 2024
@spacether work can be found in https://github.com/openapitools/openapi-json-schema-generator and he decided to host it elsewhere instead. His approach unfortunately didn't gain attraction and many Python users we contacted switched to something else instead, and therefore we refactored the Python client generator (using pydantic) and have gained many positive feedback and enhancements since the beta release.
As said before, the best way to get updates regarding OpenAPI 3.1 support (beta) is via the Label in the pull request tab: https://github.com/OpenAPITools/openapi-generator/pulls?q=+is%3Apr+label%3A%22Feature%3A+OAS+3.1.0+spec+support%22+, and raise a new issue if needed
For general feedback on OpenAPI specification, please open an issue in the official repo as this project is not affiliated with OpenAPI Initiative (OAI).