Update default OpenApi version to 3.2

[Youssef1313]

This updates the default OpenApi version to 3.2.

I think we are late enough in previews to take this change and have enough time to receive user feedback.

@halter73 @baywet @mikekistler @danroth27

Description

Updates the default OpenAPI specification version in OpenApiOptions.OpenApiVersion from OpenApi3_1 to OpenApi3_2. Apps that don't explicitly configure a version will now emit OpenAPI 3.2 documents by default. The invalid-version fallback in GetDocumentCommandWorker now also falls back to OpenApi3_2 instead of OpenApi3_1.

Motivation and Context

We are far enough along in the preview cycle to take this change and gather user feedback on the OpenAPI 3.2 default.

Testing

• Updated the OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant snapshot to reflect the new 3.2 output, including:
  • Version string changed from 3.1.2 to 3.2.0
  • QUERY HTTP method is now represented as a first-class path operation key ("query") in OpenAPI 3.2, rather than as an "x-oai-additionalOperations" extension used in 3.1
• Updated GetDocumentInsider.Tests assertions from OpenApi3_1 to OpenApi3_2 (default document, invalid-version fallback, and document-by-name tests) and the error message from "v3.1" to "v3.2"
• All 867 OpenAPI tests pass
• All 14 GetDocumentInsider.Tests pass

Additional context

[Copilot]

Pull request overview

Updates the default OpenAPI specification version used by Microsoft.AspNetCore.OpenApi.OpenApiOptions to 3.2, so apps that don’t explicitly configure a version will emit OpenAPI 3.2 documents by default.

Changes:

• Update OpenApiOptions.OpenApiVersion default from OpenApi3_1 to OpenApi3_2.
• Update the corresponding XML doc comment to reflect the new default.

[martincostello]

I checked (because I couldn't remember) and swagger-ui supports OpenAPI 3.2 now: Swagger launches support for OpenAPI 3.2.0.

Redoc doesn't yet: Redocly/redoc#2746

[baywet]

LGTM 🚀
(I had a reminder to submit a similar PR on July 15 so we don't miss the last preview boat)

[baywet]

@Youssef1313
You'll want to apply those commits I believe:

• bc92b8f
• 0544318

And you can mark this PR as fixing #65490

[Youssef1313]

@copilot Run OpenApi tests and fix the test failures.

[Copilot]

@copilot Run OpenApi tests and fix the test failures.

Done. The failing test was OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant — its snapshot expected "openapi": "3.1.2" with QUERY as an x-oai-additionalOperations extension, but with the 3.2 default it now produces "openapi": "3.2.0" with QUERY as a first-class path operation. I updated the snapshot to match the new 3.2 output in commit 2e1bddf. All 867 tests now pass.

[Youssef1313]

@copilot Fix GetDocumentInsider.Tests failures as well.

[Copilot]

@copilot Fix GetDocumentInsider.Tests failures as well.

Fixed in the latest commit. Updated three assertions in GetDocumentTests.cs that referenced OpenApi3_1 (default document, invalid-version fallback, and document-by-name tests) and the error message check from "v3.1" to "v3.2". All 14 tests now pass.

[DeagleGross]

We probably should announce this as breaking change: dotnet/AspNetCore.Docs#37228

[dotnet-policy-service]

Thanks for identifying a breaking change.

no assignees, after you commit this PR please take the following actions, as part of the breaking changes announcement process:
\n- [ ] Create an announcement issue by using the ASP.NET Core breaking change issue template.
\n- [ ] Link the breaking change announcement issue from this PR.
\n- [ ] Remove the needs-breaking-change-announcement label.

[Youssef1313]

We probably should announce this as breaking change: dotnet/AspNetCore.Docs#37228

Good point. I looked now at https://learn.microsoft.com/en-us/aspnet/core/breaking-changes/10/overview?view=aspnetcore-10.0 and there was no mention of a breaking change of switch from 2.x to 3.1 (it was done early in .NET 10, in Preview 1 I think). But I agree this should have been documented for .NET 10 (and should be for .NET 11 as well)

[Youssef1313]

@DeagleGross @mikekistler Do we need an announcement in aspnet/Announcements repo? or just docs in AspNetCore.Docs repo?