通过

弃用 WithOpenApi 扩展方法

在 .NET 10 中，WithOpenApi 方法已被弃用。 调用这些方法现在将生成编译时诊断 ASPDEPR002 ，并生成一条标准 Obsolete 警告，指出：

WithOpenApi 已弃用，将在将来的版本中删除。 有关详细信息，请访问 https://aka.ms/aspnet/deprecate/002。

已引入的版本

.NET 10 预览版 7

以前的行为

以前，可以在没有任何警告的情况下使用 WithOpenApi 扩展方法：

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

新行为

从 .NET 10 开始，使用 WithOpenApi 扩展方法生成编译器警告：

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

但是，调用仍然能够编译和执行。

破坏性变更的类型

此更改可能会影响 源兼容性。

更改原因

WithOpenApi 内置 OpenAPI 文档生成管道现在提供的重复功能。 弃用它可简化 API 图面，并为最终删除做好准备。

从代码中删除 .WithOpenApi() 调用。

  • 如果你使用了 Microsoft.AspNetCore.OpenApi 进行文档生成，请使用 AddOpenApiOperationTransformer<TBuilder>(TBuilder, Func<OpenApiOperation,OpenApiOperationTransformerContext,CancellationToken,Task>) 扩展方法。

    以前：

    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();

    之后：

    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();

  • 如果你使用过 Swashbuckle 生成文档，请使用 IOperationFilter API。

  • 如果用于 NSwag 文档生成，请使用 IOperationProcessor API。

受影响的 API