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

[kjac]

Hi everyone.

We've been back and forth on this one since Friday, and we've made a decision to upgrade the Swashbuckle dependency for V17.0, in order to avoid a breaking change later in the 17 lifetime. See #20925

The CMS will still generate OpenAPI 3.0.4 schemas as it does today.

We are still aiming for a V17.0 release on the 27th, and we're actively reaching out to the authors of most-used packages to raise awareness of this change.

Thanks to all here for raising this concern ❤️

Update: Umbraco 17-RC4 is available with this update on the preview feed (MyGet) now 👍

[kjac]

@warrenbuckley this is definitively a major thing - STS or LTS, that's not decided yet... but I would certainly expect it to be sooner rather than later 😃

[warrenbuckley]

Looking forward to it @kjac - as can try out generating OpenAPI specs at build so I can have it committed to the repo and for the site not to be running in order to generate a new strongly typed HTTP/Fetch based client with Hey-API

[bielu]

@warrenbuckley afaik you can do it now, by using swagger cli :) (I am doing it already) https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/docs/configure-and-customize-cli.md#retrieve-openapi-directly-from-a-startup-assembly
however OpenApi from microsoft package is little easier to use :)

[warrenbuckley]

Yeh managed to get that to work as well - but hoping for the MS approach to not lean on a dotnet tool installed in the project

[bielu]

ms approach is using dotnet package with tool: https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md#net-cli-1
so it is little less annoying but yeah not great either :)

[enkelmedia]

Just updated to the latest nightly (RC4). For me, this update was super simple - just had to change:

using Microsoft.OpenApi.Models;

to

using Microsoft.OpenApi;

In three places 🚀

[leekelleher]

Similar for me with Contentment, just an import namespace change:
leekelleher/umbraco-contentment@91fa579#diff-73c055556f2ccfe75fe1cbaa3fcb9257554e7143d254af29b8ec96abd50f3c1cR6-R10

[warrenbuckley]

+1 For Examine Peek for the using namespace change
warrenbuckley/Examine-Peek@0342714

[Luuk1983]

I've had to do a lot more effort, but in the end it's nothing serious. Maybe not everything is needed or could be done differently, but this is the summary for me. Hopefully it helps someone :)

Migration Guide: Swashbuckle 9 to 10 / Microsoft.OpenApi 1.x to 2.x

Namespace Changes

• Replace using Microsoft.OpenApi.Models; with using Microsoft.OpenApi;
• Add using System.Text.Json.Nodes; when working with example values

Type Changes

• Replace OpenApiString with JsonValue.Create() for string values
• Replace new OpenApiExample { Value = new OpenApiString("value") } with new OpenApiExample { Value = JsonValue.Create("value") }
• Change Dictionary<string, OpenApiExample> to Dictionary<string, IOpenApiExample> (use interface)
• Change Dictionary<string, OpenApiSchema> to Dictionary<string, IOpenApiSchema> (use interface)
• Change List{OpenApiParameter} to List {IOpenApiParameter} (use interface)
• Cast enum lists: .Select(value => JsonValue.Create(value)).Cast().ToList()

Schema Type Property

• Change OpenApiSchema.Type = "string" to OpenApiSchema.Type = JsonSchemaType.String
• Change "object" to JsonSchemaType.Object
• Change "array" to JsonSchemaType.Array
• Change "number" to JsonSchemaType.Number
• (Type is now an enum instead of a string)

Read-Only Properties

• Remove assignments to IOpenApiParameter.Required (property is now read-only)

Null Handling

• Add null checks for collections that may be nullable (e.g., operation.Responses)

[bielu]

@Luuk1983 for string values you dont need use JsonValue.Create("value"), you can just use "" :) it is supported :)

[BlagoCuljak]

[AndyButland]

No, there's no change made to 16.4.

[MiguelGuedelha]

Would a move away from having a built in UI + relying on Swashbuckle in general, and instead just depending on Microsoft.OpenApi directly be something to consider in the future?

So you can just align with the Microsoft.OpenApi version as needed in your release cycles, and adding the UI would be something done on a project by project basis. This would also allow developers to use their preferred UI package that aligns with their other services they build and support on a given project (although Swagger UI can still be used and hooked up with MS OpenAPI directly, so shipping a default UI could still be a thing regardless)

Between Swashbuckle, Scalar, etc options are a plenty nowadays besides Swagger UI and easy to integrate directly with the MS OpenApi package document generation.

[bielu]

@MiguelGuedelha it was already answered:
#20902 (reply in thread)
:) the plan is there but not specified version, it was decided to stay with swashbuckle as they are too close with release :)

[MiguelGuedelha]

Ah yes, my bad, didn't see that point in one of the threads 😄

Yes, of course in this release moving off of Swashbuckle would not be feasible, that's understandable