[REQ] Support for OpenAPI Spec 3.1

[westn]

Is your feature request related to a problem? Please describe.

Support for OpenAPI Spec 3.1, released last month: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0

Describe the solution you'd like

Add support for OpenAPI Spec 3.1

Additional context

Couldn't see any other mention of this besides a short mention in #15
Another note on https://www.openapis.org/blog/2020/06/18/openapi-3-1-0-rc0-its-here which mention that the specification-change is bigger than it sounds and might break some tooling.

[spacether]

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.

[darkbasic]

https://github.com/swagger-api/swagger-parser/commits/oas3.1

[cgfarmer4]

Any updates to share on potentially updating the generators to OAS 3.1?

[gunsluo]

Any updates to share on potentially updating the generators to OAS 3.1?

swagger-api/swagger-parser#1535, there has been no update for half a year.

[cyangle]

OAS 3.1 support has been added to swagger-parser in swagger-api/swagger-parser#1730

[denisgolubovic]

What release do you aim for this to be implemented in the generator? 6.1.0?

[kiwisincebirth]

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]

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....

[slPerryRhodan]

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]

Any updates on 3.1 support?

[Stokestack]

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]

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.

[philsturgeon]

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.

• https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
• https://www.apimatic.io/blog/2021/09/migrating-to-and-from-openapi-3-1/
• https://nordicapis.com/whats-new-in-openapi-3-1-0/

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!

[marcelstoer]

Apart from the actual lack of 3.1 support the biggest issue I have is that this project does not seem to be open about it.

The README doesn't mention it. https://openapi-generator.tech/ prominently claims

from OpenAPI 2.0/3.x documents

which led me to believe that 3.1 be fully supported.

[RickKukiela]

Probably should say 3.0.x...

[karenetheridge]

It would be helpful to see an itemized list of what is still needed to achieve v3.1 support, so that members of the community can help out. Has anyone identified those tasks?

[spacether]

It would be helpful to see an itemized list of what is still needed to achieve v3.1 support, so that members of the community can help out. Has anyone identified those tasks?

I am putting together that list now and we will publish a project very soon. This is something that we all want to add to openapi-generator. It is ~30 feature additions to store the new openapi/json schema data in our java classes. Then that data needs to be used by the generators to generate code that imposes the new json schema validation + adds new openapi features.

[spacether]

We have a project to track adding 3.1.0 support here:
https://github.com/orgs/OpenAPITools/projects/4/views/1 and welcome any PRs adding these features

Generators that will have 3.1.0 support prioritized:
#13073

Tag for 3.1.0 issues/PRs:
https://github.com/OpenAPITools/openapi-generator/issues?q=is%3Aissue+is%3Aopen+label%3A%22Feature%3A+OAS+3.1.0+spec+support%22

[adampoplawski]

Hello
Is there a plan to add support for OpenAPI 3.1 in the 7.0.0 release?

[phillipuniverse]

Any sort of updated timeline anywhere? More and more upstream projects are supporting OpenAPI 3.1. For example, FastAPI (Python project) released 0.100.0 a couple of weeks ago that targets OpenAPI 3.1 only.

I see this project at https://github.com/orgs/OpenAPITools/projects/4, but seems like very little activity in the last year. And @spacether, what's your plan with your fork? I can't quite tell how complete the OpenAPI 3.1 support is - the README still seems to indicate OpenAPI 3.0.x only. And it seems like your fork is python generator-focused.

[spacether]

Some updates on my fork, openapi-json-schema-generator

• 2.0.0 release: I have done some significant refactoring to pave the way for 3.1.0 spec processing, namely CodegenModel and CodgenProperty are both now represented by a CodegenSchema class. Java classes storing openapi spec info have been cut down by 50% to 70% PR here
• While my project contains the python client generator only at this point, in my master branch full static type checking has been added to the python code which means that this generator could be ported into other static languages like Kotlin, Java, Go etc
  • UPDATE, version 3.0.0 was released on 2023-08-16 with the below improvements
  • mypy is now passing
  • openapi document inline schemas are now generated as sequential definition
    • this means that any language can now support inline schemas of any depth at any location, and running full validations per that schema
    • this is a longstanding problem impacting many many generators in this project which I fixed
  • validation simplified, SomeSchema.validate now returns typed validated values using overloads, static languages can use this same pattern
  • there is only one java project, not the 5 sub-modules that openapi generator has
  • the first java class in the directory structure is the main entrypoint class, OpenAPIGenerator.java
  • all PythonClientCodegen.java etc classes renamed to PythonClientGenerator and are located in the generators folder
  • java 11 is used

The openapi-core team required the removal of my python generator from this repo despite it thoroughly providing openapi and json schema features, so I will no longer be contributing to this repo

If you are interested in using these features and they do not yet exist in the tooling, please write a PR in openapi-json-schema-generator

• json schema support is something that I have been working on in this code base for 4 years
• Based on contributions in this repo, I am the developer who has historically cared about this the most
  • I made the 3.1.0 spec project in this repo
  • CodegenModel.java, my account has the highest number of commits to this file, 36
  • CodegenProperty.java, my account has the highest number of commits to this file, 31
  • Ijsonschemavalidationproperties.java, my account has the highest number of commits to this file, 30
• the python client generator tests itself with the json schema test suite in the 3.0.3 unit test spec that I made
• no other generators in this repo integrated the 3_0_3_unit_test_spec despite it being here for 1 year

If you want json schema support in python or any other language please give the project a look and help me build it. PRs and new generators in any language are welcome We can all be the change that we want to see 🙂 I am actively working on adding 3.1.0 spec features here

[phillipuniverse]

@spacether thanks for the extra information. Really unfortunate that some of the drama caused the fork! Your contributions speak for themselves! Seems like there is no other hope for OpenAPI 3.1 support landing in this repo 😢

in my v3 branch full statically check typing has been added to the python code which means that this generator could be ported into other static languages like Kotlin, Java, Go etc

Nice, maybe we could use the list at #13073 for the next ones to prioritize. From this list, looks like it would be Java and typescript-axios.

[adampoplawski]

@spacether thx for info. Are you planning to suport only Python in you fork in foreseeable future?

[spacether]

My focus is getting python working for 3.1.0. If people add more languages they will be supported. So PRs and new generators in any language are welcome.

Java client users, can you provide feedback on how you would want operation methods to be generated here? https://stackoverflow.com/questions/76800939/how-should-i-write-a-method-to-make-a-rest-request-to-the-server-and-return-back
I have been thinking about how to port the python code into Java.

Does anyone here want to work on a Java client generator or a different language from python?

[abrahan-munro]

Note that if the spec document is mostly compatible with 3.0.x, just changing the version string from 3.1.0 to 3.0.3 can be used as a work around. When the version is 3.1, incorrect output is produced, but correct output may be generated if the version is 3.0. This is the case with the spec produced by the current version of FastAPI (0.100.0) for example.

[spacether]

Heads up, as of today just over 50% of the 3.1.0 new json schema keyword features have been implemented in my project: https://github.com/openapi-json-schema-tools/openapi-json-schema-generator in the master branch
Including:

• const
• contains
• dependentRequired
• dependentSchemas
• maxContains
• minContains
• patternProperties
• prefixItems
• propertyNames
• unevaluatedItems
• unevaluatedProperties

[Fares-Abubaker]

Hello all,
when supporting for 3.1.0 will be released ?

[spacether]

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.

...
LMK if you have any questions!

@philsturgeon one big roadblock is that there are a number of bugs in swagger-parser that prevent json schema test cases from running/passing. One can see 10 of those bugs here: https://github.com/swagger-api/swagger-parser/issues?q=is%3Aissue+is%3Aopen+3.1.0+author%3Aspacether
If people want these features to work, please consider helping fix these bugs in swagger-parser.
The one breaking the most test cases is: swagger-api/swagger-parser#1770

[philsturgeon]

@spacether I'm sorry to say I've got absolutely nothing to do with https://github.com/swagger-api/swagger-parser.

You're mistaking it for https://github.com/APIDevTools/swagger-parser, which I do occasionally maintain, but it's is a whole other thing.

[spacether]

Just answering your what are the roadblocks question, not saying that you are associated with swagger-parser.

[spacether]

OpenAPI v3.1.0 python code generation is now supported in openapi-json-schema-generator

Heads up, I just released v3.3.0 of openapi-json-schema-generator which allows python code generation using an openapi v3.1.0 document.

Over 66% of the 3.1.0 new json schema keyword features have been implemented
3.1.0 spec support includes these added/updated json schema keywords:

1. type (array of types supported in addition to one non-array value)
2. const: only string values are working because of bugs in swagger parser
3. contains
4. dependentRequired
5. dependentSchemas
6. maxContains
7. minContains
8. patternProperties
9. prefixItems
10. propertyNames
11. unevaluatedItems
12. unevaluatedProperties
13. if
14. then
15. else

[spacether]

@adampoplawski @phillipuniverse I have been working on a Java generator and v3.0.0-v3.0.3 openapi schema validation has been implemented in java. This includes List/Map output classes, List/Map builder classes, and Enums which are accepted into Schema.validate and the List/Map builders. Read all about it here. The Java schema validation is available in my v4.0.0 release.

[sheldonreddy]

Hi,

When can we expect the openapi specification version 3.1.0 to be supported by the OpenAPI-Generator tooling? Is there any roadmap we can reference to keep an eye on?

Thanks

[wing328]

latest stable version v7.2.0 comes with beta support. you can give it a try to see if it works for your use cases.

[sheldonreddy]

Thanks @wing328 - will give it a shot.

[spacether]

@wing328

• Where was the beta support added?
• What 3.1.0 features were added in what generators?

The only 3.1.0 PR that I see in that release is #17174 looking at the release notes and doing a search for 3.1.0

[spacether]

openapi v3.1.0 schema support added for java in openapi-json-schema-generator

Heads up, I just released v4.1.0 of openapi-json-schema-generator which allows java code generation using an openapi v3.1.0 document.

Over 67% of the 3.1.0 new json schema keyword features have been implemented
3.1.0 spec support includes these added/updated json schema keywords, which are tested with the json schema test suite in CI:

1. type (array of types supported in addition to one non-array value)
2. const: only string values are working because of bugs in swagger parser
3. contains
4. dependentRequired
5. dependentSchemas
6. maxContains
7. minContains
8. patternProperties
9. prefixItems
10. propertyNames
11. unevaluatedItems
12. unevaluatedProperties
13. if
14. then
15. else

[adampoplawski]

@wing328 Can you share the status of 3.1.0 support?

[wing328]

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+

[spacether]

openapi 3.1.0 support added for the java generator in openapi-json-schema-generator

Heads up, I just released v4.2.1 which includes the stable java sdk generator

• It includes thorough endpoint code samples for schema validation an endpoint invocation
  • Pet.addPet endpoint
  • Money schema
• Sealed classes are used for validated schema payloads/request bodies/responses/response bodies
• Code is re-used rather than generated multiple times: If an endpoint has multiple tags, the endpoint method is defined once as a default method in an interface, and that interface is implemented in each tag's api class