New Obsolete API Article: ASPDEPR002: WithOpenApi in ASP.NET Core .NET 10

[wadepickett]

Contributes to #36299

Create a new Obsolete API Article for DiagnosticID ASPDEPR002 (WithOpenApi in ASP.NET Core .NET 10)

Background

The WithOpenApi API in ASP.NET Core will be marked obsolete starting in .NET 10, with warning DiagnosticID ASPDEPR002.

References

• ASP.NET Announcements Issue #519
• Breaking Changes Documentation: withopenapi-deprecated.md
• src/OpenApi/src/Extensions/OpenApiEndpointConventionBuilderExtensions.cs
  • https://github.com/dotnet/aspnetcore/blob/release/10.0/src/OpenApi/src/Extensions/OpenApiEndpointConventionBuilderExtensions.cs
• src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Extensions/OpenApiRouteHandlerBuilderExtensionTests.cs
  • https://github.com/dotnet/aspnetcore/blob/13e009dc4992c3bcf34913831c845d77876883a8/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Extensions/OpenApiRouteHandlerBuilderExtensionTests.cs#L4

Request

Create a new Markdown documentation article for the aspnetcore.docs repo that clearly documents:

• The obsoletion of WithOpenApi in ASP.NET Core as of .NET 10.
• The assigned DiagnosticID: ASPDEPR002.
• The previous usage and the new recommended pattern for OpenAPI configuration.
• All required metadata and topic formatting as defined in breaking change documentation templates.
• How developers can suppress the warning if necessary.
• The affected API and why the change was made.
• Guidance and migration instructions for impacted projects.

The article should follow established ASP.NET Core breaking change documentation patterns (see reference markdowns and prompt template) and include all required metadata blocks, code examples, and links to relevant GitHub source issues.

Possible example format:

---

title: "ASPDEPR002: Obsoletion of WithOpenApi API in ASP.NET Core (.NET 10)"
description: "The WithOpenApi API is marked obsolete starting in .NET 10 with DiagnosticID ASPDEPR002. Using this API will warn at compile time and is no longer supported."
ms.date: 2025-11-19
ms.topic: "conceptual"
ms.custom:

• "breaking-change"
• "source-aspnet"
• "[Breaking change]: Deprecation of WithOpenApi extension method aspnet/Announcements#519"

---

ASPDEPR002: Obsoletion of WithOpenApi API in ASP.NET Core (.NET 10)

Version introduced

.NET 10

The xref:Microsoft.AspNetCore.Builder.WithOpenApi?displayProperty=nameWithType API is marked obsolete, starting in .NET 10. Using this API generates warning ASPDEPR002 at compile time and the API may not be present at runtime. Developers should transition to the new approach for OpenAPI documentation in ASP.NET Core.

For more information, see Suppress warnings.

Previous behavior

Previously, you could call WithOpenApi() in your Minimal API endpoints to automatically generate and tag OpenAPI documentation for specific routes:

app.MapGet("/weather", () => ...)
   .WithOpenApi();

This would enable basic OpenAPI description for those routes without additional configuration.

New behavior

Starting in .NET 10, WithOpenApi() is obsolete. The recommended alternative is to use full Swashbuckle or manual OpenAPI configuration instead of relying on WithOpenApi(). If you attempt to use WithOpenApi() in .NET 10, you will receive a compile-time warning:

warning ASPDEPR002: 'WithOpenApi' is obsolete: The WithOpenApi API will be removed in a future release. See https://aka.ms/aspnetcore/obsoletions.

Type of breaking change

Source incompatible

Reason for change

The API was obsoleted to streamline and centralize OpenAPI support through standard and more extensible mechanisms (such as Swashbuckle and manual endpoint metadata), and reduce reliance on convenience methods that could cause limitations and confusion.

Recommended action

Remove WithOpenApi() calls from your endpoints and use Swashbuckle or explicit OpenApi attributes/metadata where needed. Review documentation for configuring OpenAPI in ASP.NET Core projects.

Affected APIs

• Microsoft.AspNetCore.Builder.WithOpenApi

Suppress a warning

If you must use the obsolete APIs, you can suppress the warning in code or in your project file.

To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning.

// Disable the warning.
#pragma warning disable ASPDEPR002

// Code that uses obsolete API.
// ...

// Re-enable the warning.
#pragma warning restore ASPDEPR002

To suppress all the ASPDEPR002 warnings in your project, add a <NoWarn> property to your project file.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
   ...
   <NoWarn>$(NoWarn);ASPDEPR002</NoWarn>
  </PropertyGroup>
</Project>

See also

• Breaking change issue on GitHub