[Question]: Should Swashbuckle target a newer version of Microsoft.OpenApi?

[bkoelman]

What are you wanting to achieve?

The .NET 10 PR (#3283) currently references Microsoft.OpenApi v2.0, but there have been quite a few fixes since then. I currently target v2.3.9 in all my projects, which works, but it may be nice for all Swashbuckle users to benefit from recent fixes.

What code or approach do you have so far?

N/A

Additional context

No response

[martincostello]

I'm on the fence about this.

Originally I pinned the version to 2.0.0 as a baseline for running/compilation, to leave any further updates in the shipping libraries to be up to the user. If they want to upgrade, they can, but if they don't want to/don't care, then they just get what they get. However as you note there's been a lot of changes since 2.0.0 shipped (way more than I expected - 13 to-date).

The main bit I'm reticent about is Swashbuckle becoming a vehicle for Microsoft.OpenApi updates and having to ship new versions just to provide upstream fixes from microsoft/OpenAPI.NET to our own users that they can easily self-source.

The middle ground is probably to update the VersionOverride to whatever the latest is now, and then freeze it iafter 10.0.0 is published unless there's a good reason to pick up a specific new version, but it just seems a bit arbitrary to depend on a specific patch version at the point we release .NET 10 support 😄.

[bkoelman]

I agree with all of that. When adding .NET 10 support to Swashbuckle for the first time, any version can be picked. Bumping later may break existing users, so shouldn't normally happen.

As far as I'm aware, there's no universal practice in the .NET space. Some package authors prefer to reference the lowest minimal compatible version, while others ship with the latest at the time of major release. I understand both points of view, and usually lean towards the former. One argument for the latter is that otherwise users won't know if the package is compatible with the latest minor version. In practice, my choice varies per dependency, based on what's changed and what that means for consumers.

Perhaps the middle ground here would be to reference the latest minor version? Because OAS 3.1 isn't widely used yet and the changes since 2.0 don't look invasive to me for consumers.

[martincostello]

Updated to 2.3.0 in #3641.

[bkoelman]

Thanks!