Update default OpenApi version to 3.2 by Youssef1313 · Pull Request #67097 · dotnet/aspnetcore

Youssef1313 · 2026-06-09T15:22:14Z

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.

    /// <summary>
-    /// The version of the OpenAPI specification to use. Defaults to <see cref="OpenApiSpecVersion.OpenApi3_1"/>.
+    /// The version of the OpenAPI specification to use. Defaults to <see cref="OpenApiSpecVersion.OpenApi3_2"/>.
    /// </summary>
-    public OpenApiSpecVersion OpenApiVersion { get; set; } = OpenApiSpecVersion.OpenApi3_1;
+    public OpenApiSpecVersion OpenApiVersion { get; set; } = OpenApiSpecVersion.OpenApi3_2;


martincostello · 2026-06-09T15:32:10Z

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 · 2026-06-09T16:57:24Z

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

And you can mark this PR as fixing #65490

Youssef1313 · 2026-06-10T10:13:52Z

@copilot Run OpenApi tests and fix the test failures.

Co-authored-by: Youssef1313 <31348972+Youssef1313@users.noreply.github.com>

Copilot · 2026-06-10T10:25:23Z

@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 · 2026-06-10T13:44:25Z

@copilot Fix GetDocumentInsider.Tests failures as well.

Co-authored-by: Youssef1313 <31348972+Youssef1313@users.noreply.github.com>

Copilot · 2026-06-10T13:52:57Z

@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 · 2026-06-11T07:44:38Z

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:

Create an announcement issue by using the ASP.NET Core breaking change issue template.
Link the breaking change announcement issue from this PR.
Remove the needs-breaking-change-announcement label.

Youssef1313 · 2026-06-11T07:47:34Z

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 · 2026-06-11T07:49:20Z

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

danroth27 · 2026-06-11T22:26:33Z

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

@Youssef1313 We typically do both. Also, we should add guidance in the .NET 10 to .NET 11 migration guide for ASP.NET Core in the ASP.NET Core docs.

Youssef1313 · 2026-06-12T10:45:51Z

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

@Youssef1313 We typically do both. Also, we should add guidance in the .NET 10 to .NET 11 migration guide for ASP.NET Core in the ASP.NET Core docs.

@danroth27 Thanks, I'll make sure to create the announcement and update the docs once this PR merges.

Youssef1313 · 2026-06-16T08:49:59Z

@mikekistler @danroth27 Announcement: aspnet/Announcements#530

nycdotnet · 2026-07-17T15:28:50Z

@danroth27 Azure APIM doesn't yet fully support OpenAPI 3.1. I think this is a nice change, but it would be great if you could ping the APIM folks to get them to support this latest standard (and 3.1 while they're at it).

https://learn.microsoft.com/en-us/azure/api-management/api-management-api-import-restrictions

baywet · 2026-07-17T15:36:20Z

@nycdotnet thanks for sharing this. I've been working with the APIM team for the better part of a year now to get them to upgrade Microsoft.OpenAPI so the service supports newer versions of OpenAPI (both ingestion and emission).

This is currently in internal preview and being tested out before broader release. I don't have any timelines to share.

nycdotnet · 2026-07-17T17:48:18Z

@baywet amazing thank you.

Update default OpenApi version to 3.2

0682855

Copilot AI review requested due to automatic review settings June 9, 2026 15:22

Youssef1313 requested a review from a team as a code owner June 9, 2026 15:22

Copilot started reviewing on behalf of Youssef1313 June 9, 2026 15:22 View session

github-actions Bot added the needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically label Jun 9, 2026

Update GetDocumentCommandWorker.cs

7c10fb4

Copilot AI reviewed Jun 9, 2026

View reviewed changes

Update Resources.resx

a136138

baywet approved these changes Jun 9, 2026

View reviewed changes

build-analysis Bot mentioned this pull request Jun 9, 2026

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

3 tasks

Copilot started work on behalf of Youssef1313 June 10, 2026 10:14 View session

Update localization snapshot for OpenAPI 3.2 default

e941479

Co-authored-by: Youssef1313 <31348972+Youssef1313@users.noreply.github.com>

Copilot finished work on behalf of Youssef1313 June 10, 2026 10:25

Youssef1313 added feature-openapi area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc and removed needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically labels Jun 10, 2026

Copilot started work on behalf of Youssef1313 June 10, 2026 13:44 View session

Fix GetDocumentInsider.Tests for OpenAPI 3.2 default

5a26eb8

Co-authored-by: Youssef1313 <31348972+Youssef1313@users.noreply.github.com>

Copilot finished work on behalf of Youssef1313 June 10, 2026 13:53

Update GetDocumentTests.cs

febec96

build-analysis Bot mentioned this pull request Jun 10, 2026

slow macOS - "##[error]The job running on agent Azure Pipelines 9 ran longer than the maximum time of 60 minutes." dotnet/dnceng#1883

Open

3 tasks

DeagleGross approved these changes Jun 11, 2026

View reviewed changes

Youssef1313 added breaking-change This issue / pr will introduce a breaking change, when resolved / merged. needs-breaking-change-announcement Indicates that breaking change announcement shuold be posted and linked to this PR labels Jun 11, 2026

Merge branch 'main' into dev/ygerges/openapi-3-2

198254d

Youssef1313 merged commit 423e407 into main Jun 16, 2026
25 checks passed

Youssef1313 deleted the dev/ygerges/openapi-3-2 branch June 16, 2026 08:43

Youssef1313 removed the needs-breaking-change-announcement Indicates that breaking change announcement shuold be posted and linked to this PR label Jun 16, 2026

dotnet-maestro Bot mentioned this pull request Jun 23, 2026

[main] Source code updates from dotnet/aspnetcore dotnet/dotnet#7330

Merged

dotnet-milestone-bot Bot added this to the 11.0-preview6 milestone Jun 23, 2026

This was referenced Jun 29, 2026

OpenAPI 3.2.0 - aspnet11 - default emitted version to 3.2.0 #65490

Closed

OpenAPI 3.2.0 just released #63754

Closed

Uh oh!

Conversation

Youssef1313 commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

Testing

Additional context

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

martincostello commented Jun 9, 2026

Uh oh!

baywet left a comment

Choose a reason for hiding this comment

Uh oh!

baywet commented Jun 9, 2026

Uh oh!

Youssef1313 commented Jun 10, 2026

Uh oh!

Copilot AI commented Jun 10, 2026

Uh oh!

Youssef1313 commented Jun 10, 2026

Uh oh!

Copilot AI commented Jun 10, 2026

Uh oh!

DeagleGross left a comment

Choose a reason for hiding this comment

Uh oh!

dotnet-policy-service Bot commented Jun 11, 2026 • edited by Youssef1313 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Youssef1313 commented Jun 11, 2026

Uh oh!

Youssef1313 commented Jun 11, 2026

Uh oh!

danroth27 commented Jun 11, 2026

Uh oh!

Youssef1313 commented Jun 12, 2026

Uh oh!

Uh oh!

Youssef1313 commented Jun 16, 2026

Uh oh!

nycdotnet commented Jul 17, 2026

Uh oh!

baywet commented Jul 17, 2026

Uh oh!

nycdotnet commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Youssef1313 commented Jun 9, 2026 •

edited

Loading

dotnet-policy-service Bot commented Jun 11, 2026 •

edited by Youssef1313

Loading