Support .NET 10

[martincostello]

Add support for .NET 10 and update Microsoft.OpenApi from v1 to v2.

This was started from #3252 and is very much a work-in-progress at this stage. The tests need more work to get them passing.

The general idea is to factor out any differences into shared helped classes that can be used to localise the Microsoft.OpenApi differences to as few places as possible. Once this gets further along, some of these changes can be cherry-picked into a new branch and merged into the default branch to minimise the diff for adding .NET 10 support. #3285

TODO

Before merge:

• Use stable version of .NET 10 SDK
• Use stable versions of Microsoft.AspNetCore NuGet packages
• Use stable version of Microsoft.OpenApi 2.x.x
• Remove NU5104 suppression
• Remove WebHostBuilder from tests
• Remove workarounds for prerelease issues
• Check VersionPrefix is correct for the next major version at the time of merge
• Use OpenApiDocument.SerializeAs() method
• Remove any members decorated with [Obsolete] that are appropriate
• Update documentation samples (e.g. IOpenApiSchema to OpenApiSchema) (Update documentation for v10 and OpenAPI 3.1 #3585)
• Create migration guide (see 📖 De-monolith the README #3365)
  • Include details such as for [Question]: With dotnet-vnext what's the equivalent code for .AddSecurityRequirement(...)? #3382
• Consume new .NET 10 Description properties where appropriate (see [Feature request]: Support for OpenAPI Description in [ProducesResponseType], [Produces], and [ProducesDefaultResponseType] Attributes #3099)

---

Prerelease builds from this PR can be consumed from MyGet:

<PackageReference Include="Swashbuckle.AspNetCore" Version="10.0.0-pr.3283.*" />

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="domaindrivendev" value="https://www.myget.org/F/domaindrivendev/api/v3/index.json" />
    <add key="NuGet" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

[martincostello]

Some of the failing tests are microsoft/OpenAPI.NET#2109.

Probably need to wait until .NET 10 preview 2 updates to a newer version of Microsoft.OpenApi to ingest any fixes.

[martincostello]

Moved some of the changes into #3286 so we can prepare users for the change and also then change this PR to remove SerializeAsV2 completely.

[captainsafia]

@martincostello It seems like based on this changeset Swashbuckle.AspNetCore will have a similar constraint to Microsoft.AspNetCore.OpenApi in that OpenAPI 2.0 is only used for .NET 10+ above.

Any thoughts about figuring out a way to support 2.0 in .NET 8 and .NET 9?

[martincostello]

Not yet - I figured I'd start with the "easiest" option and get everything compiling and passing to unblock any apps using .NET 10, and then go from there.

I'm going to do some more work on this tomorrow(?) probably to try and get the tests passing, though I imagine I'll have to rejig a bunch of stuff next week anyway when 10.0.0-preview.2/2.0.0-preview7(?) ship.

Ideally OpenAPI 3.1 can be made available for our 8 and 9 users, but I'm slightly wary of the bigger "compatibility cliff" that creates with all the breaking changes and any other libraries that might extend Swashbuckle.

Good job there's another 7-8 months left to work that out on our side 😆

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.33728% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.75%. Comparing base (2b7afec) to head (bd437bb).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...ggerGen/SchemaGenerator/OpenApiSchemaExtensions.cs	83.33%	6 Missing ⚠️
....AspNetCore.Annotations/AnnotationsSchemaFilter.cs	91.66%	1 Missing ⚠️
...NetCore.ApiTesting/JsonValidation/JsonValidator.cs	66.66%	1 Missing ⚠️
...re.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs	98.71%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3283      +/-   ##
==========================================
+ Coverage   94.28%   94.75%   +0.46%     
==========================================
  Files         110      110              
  Lines        3816     3831      +15     
  Branches      723      760      +37     
==========================================
+ Hits         3598     3630      +32     
+ Misses        218      201      -17     

Flag	Coverage Δ
Linux	94.75% <97.33%> (+0.46%)	⬆️
Windows	94.75% <97.33%> (+0.46%)	⬆️
macOS	94.75% <97.33%> (+0.46%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[martincostello]

Issue discovered via martincostello/aspnetcore-openapi#231 is that in some cases schema references go missing (like this one).

I'm not sure why and there's been a lot of API changes in that area since 2.0.0-preview5, so will have to wait until I've reacted to whatever changes ASP.NET Core 10 preview 2 brings and go from there.

[martincostello]

Also, preview5 => preview6 brings in more huge breaking changes (OpenApiSchema becomes IOpenApiSchema and causes OpenApiReference.Schema to no longer work) so that might force our hand on whether we do multi-targeting or not, as it might cause an explosion of #if directives and make the code too hard to deal with the differences between v1 and v2. It's especially difficult as those types come out of our public API surface, so it's not just an internal implementation detail we can work around like with JsonSchemaType/string.

[captainsafia]

@martincostello Yes, I should've warned you that the preview6 breaking changes are a bit of a pain to wrangle. Here's the PR where I did it for ASP.NET Core in case it is helpful (dotnet/aspnetcore#60269). The code surface in ASP.NET Core is admittedly smaller so most of the changes needed to be made in tests where I took shortcuts and used explicit casts for things I knew should be OpenApiSchemaReference for example.

OpenApiSchema becomes IOpenApiSchema and causes OpenApiReference.Schema to no longer work

You've probably already gleened this from the implementation, but OpenApiSchema with a Reference becomes OpenApiSchemaReference. You should be able to resolve the properties on it directly and OpenAPI.NET will resolve to the underlying target.

This is assuming that the reference has been correctly initialized in the OpenAPI document's workspace. Here is an extension method that I wrote in ASP.NET Core to help with this registration.

[martincostello]

Thanks for the pointers @captainsafia - I'll use those for reference once I start reacting to 10.0.0-preview.2 changes 🙇