Should this library start defaulting to OpenAPI 3.1?

[ross-paypay]

Currently springdoc.api-docs.version defaults to 3.0, but 3.1 has been released multiple years ago.

This can be changed pretty easily by changing the config like:

springdoc:
  api-docs:
    version: openapi_3_1

I am thinking that perhaps its time to start defaulting to 3.1?
I suppose this would be a breaking change and would require a major semver bump.

[bnasslahsen]

@ross-paypay,

For now, 3.0 is the most widely used in the market, and changing it from the default, might cause a lot of inconvenience.
The property option seem to be the solution right in the middle for now, but it might change in the future if there are so many requests.

[bgalek]

@bnasslahsen
Ability to update springdoc.api-docs.version property is great, but it's not increasing a 3.1 adaptation.
On the other hand, having 3.1 as default with ability to downgrade to 3.0 (via springdoc.api-docs.version) would be even better.

• people who don't care would have up-to-date (and more capable) version
• people who need to set springdoc.api-docs.version=openapi_3_1 in each app would not be pinning version anymore
• people who cannot update to 3.1 will need to downgrade BUT won't be blocking those who can

Could you please talk about this again in your team? :)

My context:
Consider the following use case, where a shared structure—such as Price with amount and currency fields—needs to be mandatory in one context but optional in another. In many programming languages (such as Java or Kotlin), this can be easily managed by specifying nullability in the particular context where the structure is used, without needing to redefine the structure itself.

OpenAPI 3.0 only allows "nullability" to be defined at the schema level, not at the context of use. This restriction means that if Price is defined as mandatory, it must be mandatory in all contexts, and if defined as optional, it must be optional in all contexts.

[bgalek]

@bnasslahsen @edudar @ross-paypay WDYT? :)

[bnasslahsen]

@bgalek,

There aren't many votes for the enhancement request.

As mentioned earlier, version 3.0 is the most widely used in the market, and changing the default behavior would likely cause disruption for users. Those in the minority (right now) who prefer version 3.1 should configure the property to enable it.

[bgalek]

Hi!

There aren't many votes for the enhancement request.

where can community vote? (this issue was closed day after submitting :D)
do we have any telemetry or some data, that would show usage?

[bnasslahsen]

@bgalek,

I saw the current community vote, in the first message, but to make sure we have a wider coverage:

I am creating an official one, until the end of the year to decide:

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

[bgalek]

@bnasslahsen NICE! :)