chore(main): release 3.0.0

[release-please-token-provider]

🤖 I have created a release beep boop

3.0.0 (2025-11-11)

⚠ BREAKING CHANGES

• adds support for OpenAPI 3.2.0

Features

• adds support for OpenAPI 3.2.0 (765a8dd)

---

This PR was generated with Release Please. See documentation.

[release-please-token-provider]

🤖 Created releases:

• v3.0.0

🌻

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[martincostello]

Really frustrating that this shipped today when it's only just been possible to ship stable support to users for .NET 10 GA and Microsoft.OpenApi 2.x.

[baywet]

Yes, however the standard itself released only a week or two before the code freeze for net 10. And we couldn't plan for that since there was no target date itself for the standard new version. It's unfortunate but dates can't always line up as we want 🙂

[martincostello]

Sure, but it would have been useful to "social media calendar" it, as it were, to let the dust settle a bit first for .NET 10 and .NETConf, and also had some advance notice to make some preparation in Swashbuckle.AspNetCore.

Instead within 2 hours of shipping a new major release that's been in development for 10 months, Swashbuckle.AspNetCore is already targeting an older major version and needs another major release for breaking changes.

[baywet]

Maybe @captainsafia can provide additional feedback here for the ASP.net support, but as far as I understand it, it won't be available before net 11 (so a year from now?).
As for the version 2.X, it'll receive servicing as documented in the contributing guidelines, while this is not ideal, it'll allow Swashbuckle (and other projects) to get all the support they need.

[martincostello]

The built-in support for Microsoft.AspNetCore.OpenApi won't be able to use it no. I already tried it out, and the source generator in ASP.NET Core 10 fails to compile if 3.0.0 is used due to the breaking change for OpenApiMediaType to IOpenApiMediaType, so it will need to wait until November 2026 and .NET 11 for use there (in a stable version).

For example from a renovate PR I just got:

Error: /home/runner/work/alexa-london-travel-site/alexa-london-travel-site/artifacts/obj/LondonTravel.Site/release/Microsoft.AspNetCore.OpenApi.SourceGenerators/Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator/OpenApiXmlCommentSupport.generated.cs(725,41): error CS0200: Property or indexer 'IOpenApiMediaType.Example' cannot be assigned to -- it is read only [/home/runner/work/alexa-london-travel-site/alexa-london-travel-site/src/LondonTravel.Site/LondonTravel.Site.csproj]

I've already opened a PR for Swashbuckle.AspNetCore which should be able to adopt it relatively soon (domaindrivendev/Swashbuckle.AspNetCore#3646) as it isn't as tied to Microsoft.AspNetCore.OpenApi for .NET 10+. I just need to test it more and see what happens in some real ASP.NET Core apps.

Unfortunately I have a hunch that I'll now get a bunch of bug reports from people who'll "just update everything to latest" and then report that Swashbuckle.AspNetCore doesn't work with Microsoft.OpenApi 3.x.

If there'd been a bit of coordination and breathing room, that could have maybe been avoided or deferred for a bit. Of course I'm making an assumption here and maybe it'll all be fine in reality, but past experience with new major .NET releases doesn't make me hopeful.

[baywet]

Thank you for the additional information.

Sorry, I got mixed up, I though Swashbuckle was always relying on Microsoft.AspNetCore.OpenApi but it's not the case. No I understand the initial frustration better. Swashbuckle (the part that generates the OpenAPI description) could have essentially "skipped" v2, and gone straight to v3 have you had a heads up. It doesn't need to wait for net 11. Sorry about that.

Let us know if you find that some specific documentation or release note can be improved for this scenario. (v10 people need to stay on v2, v11 people on v3)

[martincostello]

FYI, here's an example of an issue from a user updating everything as part of their .NET 10 upgrade and then finding things don't work: dotnet/aspnetcore#64317