不建議使用WithOpenApi擴充方法

WithOpenApi方法已在 .NET 10 中已被取代。 叫用這些方法現在會產生編譯時診斷 ASPDEPR002 和標準 Obsolete 警告，指出：

WithOpenApi 已被取代，未來版本將會移除。 如需詳細資訊，請瀏覽：https://aka.ms/aspnet/deprecate/002。

推出的版本

.NET 10 Preview 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

• Microsoft.AspNetCore.Builder.OpenApiEndpointConventionBuilderExtensions.WithOpenApi