Should we adopt OpenAPI 3.1 as the default implementation for springdoc-openapi?

[bnasslahsen]

We’re exploring the idea of adopting OpenAPI 3.1 as the default specification for springdoc.api-docs.version, replacing the current default of 3.0 (released several years ago). 🌟

Your feedback is crucial as we aim to align with the community’s needs and preferences.

👉 Cast your vote in our poll and let us know:

🗓 Poll closes on 31/12/2024.

Have a say in how we move forward! 💡

[bgalek]

@edudar
@baromojm
:)

[bgalek]

I've engaged some communities ;)
i.e.:
https://discord.com/channels/699965319883784252/718132459484741710/1310564047833534537

[bgalek]

@erosb pointed out, v4 spec is coming!
https://github.com/OAI/sig-moonwalk

[bgalek]

Important OpenAPITools/openapi-generator#9083 (comment)

[erosb]

Hello, let me share some thoughts on this effort.

I do strongly support using OpenAPI 3.1, because it uses JSON Schema 2020-12. That is much more expressive and powerful than OpenAPI 3.0 which uses JSON Schema Draft-4 (released in 2013 January - almost 12 years ago!).

Yet, I would question how much sense does it make to generate an openapi description from java code (like springdoc does), or the other way around, generate java code from an openapi description. There is a vast impedance between JSON Schema and the java type system, hence I doubt if such translation / code generation can be reliably implemented. For simple cases it may work OK, but JSON Schema has plenty of features that don't directly translate to type systems of programming languages. A few examples: allOf, anyOf, oneOf, not, if-then-else, contains, dependentRequired, dependentSchemas, prefixItems, $dynamicRef.

So, when generating java code from an openapi description, it is easy to simply loose a lot of constraints / metadata, or the generated code becomes very complex and hard to reason about.

The other way around, when generating openapi description from java code, the generated content won't make use of many of the available features, or it may need plenty of additional metadata (annotations) to do so.

Overall, I think when translating JSON Schema from / to java code, a lot of expressiveness of JSON Schema is lost. In the past years I haven't seen any reliable & high-quality generator in neither directions - please point me to any generators that are known to work well on nontrivial schemas, if you know about any.

To sum up, moving forward, IMO it would make a lot of sense for the community to focus on tooling that lets developers incorporate OpenAPI documents into their workflows for the purpose of validation and verification, rather than translating / generating code in one direction or the other.

Happy to hear others opinion as well on this matter. WDYT?

[bgalek]

Happy New Year!
@bnasslahsen, just a reminder: this poll was closed at the end of 2024!
I hope that you and the team will find time to discuss adopting 3.1 as default again - now with some arguments and data ;)

[bnasslahsen]

@bgalek,

The next release, will set default to OpenAPI 3.1!

[bgalek]

This is great news! 🎉

[dzoech]

Some quick feedback: I would've appreciated this switch to happen with a new major version release. Unfortunately, our automated updates for minor releases broke a couple of things which we only noticed by luck.
Nevertheless, thank you for the efforts you put into this library :)

[dalbani]

Isn't there a small issue with the default value in spring-configuration-metadata.json?

    {
      "name": "springdoc.api-docs.version",
      "type": "org.springdoc.core.properties.SpringDocConfigProperties$ApiDocs$OpenApiVersion",
      "description": "The OpenAPI version.",
      "sourceType": "org.springdoc.core.properties.SpringDocConfigProperties$ApiDocs",
      "defaultValue": "openapi-3-1"
    }

As shown in IntelliJ for example: