[Breaking change]: Deprecation of `WithOpenApi` extension method

[captainsafia]

Description

The WithOpenApi extension methods in Microsoft.AspNetCore.OpenApi.OpenApiEndpointConventionBuilderExtensions have been deprecated. Invoking these methods now produces the compile-time diagnostic ASPDEPR002 and a standard [Obsolete] warning stating that “WithOpenApi is deprecated and will be removed in a future release. For more information, visit https://aka.ms/aspnet/deprecate/002.”

Version

.NET 10 Preview 7

Previous behavior

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

New behavior

app.MapGet("/weather", () => ..)
   .WithOpenApi();   // warning ASPDEPR002: WithOpenApi is deprecated …

The call still compiles and executes, but the build now emits the new deprecation warning.

Type of breaking change

• Binary incompatible
• Source incompatible
• Behavioral change (new compiler warning)

Reason for change

WithOpenApi duplicated functionality now provided by the built-in OpenAPI document generation pipeline. Deprecating it simplifies the API surface and prepares for its eventual removal.

Recommended action

Remove .WithOpenApi() calls in the code.

• If using Microsoft.AspNetCore.OpenApi for document generation, use with AddOpenApiOperationTransformer extension method.

Before

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.MapGet("/weather", () => ..)
   .WithOpenApi(operation =>
   {
       // Per-endpoint tweaks
       operation.Summary     = "Gets the current weather report.";
       operation.Description = "Returns a short description and emoji.";
       return operation;
   });

app.Run();

After

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.MapGet("/weather", () => ..)
   .AddOpenApiOperationTransformer((opperation, context, ct) =>
   {
       // Per-endpoint tweaks
       operation.Summary     = "Gets the current weather report.";
       operation.Description = "Returns a short description and emoji.";
       return Task.CompleteTask;
   });

app.Run();

• If using Swashbuckle for document generation, use the IOperationFilter API.
• If using NSwag for document generation, use the IOperationProcessor API.

Affected APIs

• TBuilder OpenApiEndpointConventionBuilderExtensions.WithOpenApi<TBuilder>(this TBuilder builder)
• TBuilder OpenApiEndpointConventionBuilderExtensions.WithOpenApi<TBuilder>(this TBuilder builder, Func<OpenApiOperation, OpenApiOperation> configureOperation)
  (all overloads)