Skip to content

Should this library start defaulting to OpenAPI 3.1? #2765

Closed

Description

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

Activity

  1. bnasslahsen commented on Oct 16, 2024

    @bnasslahsen
    Collaborator

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

  2. bgalek commented on Nov 14, 2024

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

  3. bgalek commented on Nov 25, 2024

    @bgalek
  4. bnasslahsen commented on Nov 25, 2024

    @bnasslahsen
    Collaborator

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

  5. bgalek commented on Nov 25, 2024

    @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?

  6. bnasslahsen commented on Nov 25, 2024

    @bnasslahsen
    Collaborator

    @bgalek,

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

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

  7. bgalek commented on Nov 25, 2024

    @bgalek

    @bnasslahsen NICE! :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    questionFurther information is requested

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions