v17 should use swashbuckle 10

[bielu]

When upgrading my code to v17 i noticed umbraco v17-rc2 is using swashbuckle v 9.0.6, however for .net 10 is better to use v10.
For reference release logs for v10:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases/tag/v10.0.0
I recommend using 10.0.1 however with small fixes :)
There is upgrade guide:
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/docs/migrating-to-v10.md
There is a lot important changes in v10, like proper support for openapi 3.1. :)

[kjac]

Hi @bielu

Thanks for reaching out with this 💪

It's been on our radar, but we have chosen to forego this for a few reasons.

First of all, the v10.0 release of Swashbuckle.AspNetCore was out on the 11th, well into the RC period for Umbraco 17. At that point it was in principle too late to include it. And it would definitively be too late to bump our OpenAPI schemas to 3.1, so we'd have to stay on 3.0.4 regardless (but of course, with a per-site option to move to 3.1).

The main reason, however, is that we're investigating a move to Microsoft.AspNetCore.OpenApi in an upcoming Umbraco major, which will also bring OpenApi 3.1.

Of course, one does not necessarily exclude the other, but... since both bring about breaking changes for anyone generating custom schemas, we don't want to introduce additional breakage in Umbraco 17, if we're going to replace the whole thing and break it all over again in Umbraco 18+.

[bielu]

hey @kjac,
changes to work with custom schema are minimal, however about working with 3.1, you could have choose to deliver still with 3.0 instead, but use v10 to allow people which want use 3.1 (such as me) to make that decision for them self.
quoting docs:

By default, to minimise breaking behavioural changes, Swashbuckle.AspNetCore v10+ will continue to produce OpenAPI 3.0 documents by default.
To upgrade your OpenAPI documents to output using version 3.1 of the OpenAPI specification, you can override the version as shown in the code snippet below.

so i think that decision is not good, as it introduce you a lot technical debt, also if you upgrade to v10, you will have easier life to switch fully to Microsoft.AspNetCore.OpenApi. However it is cost of sticking to halve year release cycles, not enough time to include all important things in LTS. (Yes i consider that change as important as it as 3.1 is already 4 years old..., 3.2 was just released so not expecting it to be adapted, however 3.1 is something what should be in LTS version...)

[bielu]

Also if you check this docs:
https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy
it is not recommend staying on v1 for MIcrosoft.OpenApi as it is EOL by November 2026, and afaik v17 is going to be supported longer?

[KevinJump]

Hi,

To add some extra information - we have already seen two issues raised for this against the uSync repo

• [BETA FEEDBACK] - Microsoft.OpenApi possible issue KevinJump/uSync#854
• "Apply" method Exception on start-up when using umbraco 17 RC. KevinJump/uSync#861
  (in these case if you remove uSync you still get the error, it's just the uSync one gets hit first)

But upgrading to v10.* is a big breaking change (to be honest it's a shocking breaking change by Microsoft this one!).

The Missing apply method in our case if from having a custom IOperationFilter (which we have inheriting from BackOfficeSecurityRequirementsOperationFilterBase) that has no apply method.

The core base class having this might mitigate the issue, but there is also the fact that they have moved the namespace for the models. so the OpenApiInfo model is no longer in Microsoft.OpenApi.Models but Microsoft.OpenApi which is also another binary breaking change (e.g we will have to change code anre rebuild everything!)

if this changed before the release it would break all packages that use IOperationFilters or indeed have Custom SwaggerGenOption configure code ? (e.g almost all of them?)

[bielu]

@KevinJump yeah it would broke all packages using IOperationFilters, however v1 of OpenApi from Microsoft is almost EOL, so it shouldn't be used on LTS, Also when I looked into adjustments they are smaller than you would assume, but yeah most of them would have to happen in Umbraco. There are patterns which would allow to make it work with legacy SwaggerGenOption, however Swashbuckle made decision to not use them.

[KevinJump]

I agree , but changing this today (7 days from release) will break the majority of external packages, so its quite the thing to do. ( If it was me 😉 - i would release RC4 with this change next week and push the release back 2 weeks to give people time to migrtate)

[bielu]

I agree , but changing this today (7 days from release) will break the majority of external packages, so its quite the thing to do. ( If it was me 😉 - i would release RC4 with this change next week and push the release back 2 weeks to give people time to migrtate)

that is what i would do as well :), however umbraco said no delaying releases when they switch to this halve year cycles so i doubt they will adapt v10 or delay release :)

[kjac]

Hi both of you 👋

Also if you check this docs:
https://github.com/microsoft/OpenAPI.NET/blob/main/CONTRIBUTING.md#branches-and-support-policy
it is not recommend staying on v1 for MIcrosoft.OpenApi as it is EOL by November 26, and afaik v17 is going to be supported longer?

☝️ This just goes to show that the Umbraco community is the best! 💯

We're going to have to reevaluate matters based on the EOL of the MIcrosoft.OpenApi version we're using. At this point, I see two options for V17:

1. Either upgrade MIcrosoft.OpenApi immediately and push back the release, to give everyone a chance to update their dependencies, or
2. Plan for a breaking change in one of the minor releases, in order to upgrade MIcrosoft.OpenApi.

None of these options are any kind of desirable.

As of right now, the latter option is likely the most realistic one. I will get back to you with more information early next week.

[bielu]

i raised pr, it was really slight changes in umbraco source code, however i kept is as openapi 3.0 with upgrade, with option to enable 3.1 :)
https://github.com/umbraco/Umbraco-CMS/pull/20924/files

[BlagoCuljak]

Hope we get a new RC soon with this, I would also like to migrate and test as well, as hitting same issue as everyone else, while 27th Nov is coming in fast. :)

Feels more like an action movie, less like a software platform. :)

[iOvergaard]

We are racing to see what we can do before the release. You can follow this preliminary PR where we upgrade Swashbuckle: #20925

[Luuk1983]

Although it can probably not always be avoided, I really REALLY would hate breaking changes in minor versions. That goes against the idea of having major versions. Isn't there a way - if it cant get into the v17 release on time - to solve this non breaking by keeping the old in as obsolete?

[iOvergaard]

We are racing to see what we can do before the release. You can follow this preliminary PR where we upgrade Swashbuckle: #20925