Edit

Share via

Deprecation of WithOpenApi extension method

The WithOpenApi methods have been deprecated in .NET 10. Invoking these methods now produces the compile-time diagnostic ASPDEPR002 and a standard Obsolete warning that states:

WithOpenApi is deprecated and will be removed in a future release. For more information, visit https://aka.ms/aspnet/deprecate/002.

Version introduced

.NET 10 Preview 7

Previous behavior

Previously, you could use the WithOpenApi extension method without any warnings:

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

New behavior

Starting in .NET 10, using the WithOpenApi extension method produces a compiler warning:

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

However, the call still compiles and executes.

Type of breaking change

This change can affect source compatibility.

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.

Remove .WithOpenApi() calls from your code.

  • If you used Microsoft.AspNetCore.OpenApi for document generation, use the AddOpenApiOperationTransformer<TBuilder>(TBuilder, Func<OpenApiOperation,OpenApiOperationTransformerContext,CancellationToken,Task>) 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((operation, context, ct) =>
   {
       // Per-endpoint tweaks
       operation.Summary     = "Gets the current weather report.";
       operation.Description = "Returns a short description and emoji.";
       return Task.CompletedTask;
   });

app.Run();

  • If you used Swashbuckle for document generation, use the IOperationFilter API.

  • If you used NSwag for document generation, use the IOperationProcessor API.

Affected APIs