WithOpenApi 拡張メソッドの廃止

.NET 10 では、 WithOpenApi メソッドは非推奨になりました。 これらのメソッドを呼び出すと、コンパイル時の診断 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