ASP.NET Coreにおける Web APIの最新情報 株式会社SAKURUG プロダクトDiv 草場 友光 .NETラボ勉強会2025年01月

自己紹介 • コミュニティ活動を通じて知識を アップデートしています。 • 2022/08-2025 Microsoft MVP (Developer Technologies) • tomo_kusaba

注意 • 個人の見解・解釈が多分に入っています。 • 見解の相違・事実誤認などありましたらご指摘ください。 • #dotnetlabでtweetすると左側に表示されます

今日の目的 • ASP.NET CoreではWeb APIを実装する方法が2通りありま す。 • さらに、.NET 9においてOpen APIのドキュメント生成に関して のサポートがされました。 • 近年のWebアプリケーションにおいてWeb APIの実装は重要さ をますます増しています。 • そこで一通りのおさらいをしていきたいと思います。

.NET Core 2.2 • SwashbuckleやNSwagといったコミュニティ主導のプロジェ クトでOpenAPIをサポート

.NET 5.0 • ASP.NET Core API テンプレートにSwashbuckleのライブ ラリによるOpenAPIサポートが既定で有効化 • 既定でOpenAPIドキュメントの生成 • 既定でSwagger UIの提供

.NET 6.0 • Minimal APIのサポート

.NET 9.0 • OpenAPIドキュメント生成の組み込みサポート

2通りの実装方法 • コントローラーベースのWeb API • Minimal API

コントローラーベースのWebAPI • Program.cs var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddOpenApi(); var app = builder.Build(); if (app.Environment.IsDevelopment()) { app.MapOpenApi(); } app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers(); app.Run(); .net/MuseWiki/

コントローラーベースのWebAPI • WeatherForecastController.cs [ApiController] [Route("[controller]")] public class WeatherForecastController(ILogger logger) : ControllerBase { private static readonly string[] Summaries = [ "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" ]; private readonly ILogger _logger = logger; [HttpGet(Name = "GetWeatherForecast")] public IEnumerable Get() { _logger.LogInformation("Getting weather forecast"); return [.. Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), TemperatureC = Random.Shared.Next(-20, 55), Summary = Summaries[Random.Shared.Next(Summaries.Length)] })]; } }

Minimal API var builder = WebApplication.CreateBuilder(args); // Add services to the container. // Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi builder.Services.AddOpenApi(); var app = builder.Build(); // Configure the HTTP request pipeline. if (app.Environment.IsDevelopment()) { app.MapOpenApi(); } app.UseHttpsRedirection(); string[] summaries = [ "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" ]; app.MapGet("/weatherforecast", () => { WeatherForecast[] forecast = [.. Enumerable.Range(1, 5).Select(index => new WeatherForecast ( DateOnly.FromDateTime(DateTime.Now.AddDays(index)), Random.Shared.Next(-20, 55), summaries[Random.Shared.Next(summaries.Length)] ))]; return TypedResults.Ok(forecast); }) .WithName("GetWeatherForecast"); app.Run(); internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary) { public int TemperatureF => 32 + (int)(TemperatureC / 0.5556); } • Program.cs

できることはコントローラーベースのが多 い • 一番大きいところはモデル検証(IModelValidator)のサポート がMinimal APIにはないこと。 • コントローラーベースのAPIではモデル検証によって自動的に４０ ０応答が返される機能があります。

処理速度はMinimal APIのほうが優位 • 負荷テストをJMeterにて実施 • テスト条件を以下のように設定 • スレッド数：3000 • ランプアップ期間：5秒 • ループ回数：10回

同時実行速度はMinimal APIのほうが優位 Average Median Throuhtput Received KB/sec コントローラベース 108 41 4422.2/sec 2361.33 Minimal API 59 16 4773.3/sec 2549.01 Minimal APIの方が多くのリクエストを捌ける印象あり

Minimal APIでも実用に耐えるよね • 問題点1：Program.csにすべて書きがち →別にProgram.csに書く必要はない • 問題点2：MapGet以下にすべてを書きがち →別のメソッドに移動することですっきりするし何ならテスト もしやすくなる • 問題点3：モデル検証のサポートがない →FluentVaidationなどを活用する

Program.csにすべて書きがち問題 • Minimal APIはProgram.csに配置する必要はありません。 using MinAPISeparateFile; var builder = WebApplication.CreateSlimBuilder(args); var app = builder.Build(); TodoEndpoints.Map(app); app.Run(); using Logic; using Model; namespace MinAPISeparateFile; public static class TodoEndpoints { public static void Map(WebApplication app) { app.MapGet("/todos", () => { var todos = new[] { new Todo { Id = 1, Title = "Do something" }, new Todo { Id = 2, Title = "Do something 2" } }; return Results.Ok(todos); }); app.MapGet("/todos/{id}",(int id) => { var todo = new Todo { Id = id, Title = $"Do something{id}" }; return Results.Ok(todo); }); } } ここを増やせばよい 実装側

MapGet以下にすべてを書きがち問題 • MapGet以下に実装を書く必要はありません namespace MinAPISeparateFile; public static class TodoEndpoints { public static void Map(WebApplication app) { app.MapGet("/todos", TodoLogic.GetTodos); app.MapGet("/todos/{id}", TodoLogic.GetTodoById); } } using Model; using Microsoft.AspNetCore.Http.HttpResults; namespace Logic; public static class TodoLogic { public static Ok GetTodos() { var todos = new[] { new Todo { Id = 1, Title = "Do something" }, new Todo { Id = 2, Title = "Do something else" } }; return TypedResults.Ok(todos); } public static Ok GetTodoById(int id) { var todo = new Todo { Id = id, Title = "Do something" }; return TypedResults.Ok(todo); } }

どのように選択すればいいの？ • 個人的所感ですが・・・従来のモデル検証をまだ使いたいかどうか によるのかな？？と • 保守性やらそのあたりはどちらでも大差はないレベルかと

Open APIについて • HTTP APIをドキュメント化するためのプログラミング言語に依 存しない標準 • 次の3つの重要な側面がある • アプリ内のエンドポイントに関する情報を生成 • OpenAPIスキーマーに一致する形式で情報を収集 • 生成されたOpenAPIドキュメントをUIまたはシリアル化されたファイル を通じて公開する

Swashbuckleについて • .NET 8以前 コミュニティ提供のOpenAPIを提供するライブラ リーとして標準的に使用されていた。 • テンプレートにも組み込まれていた。 • .NET 9以降はMicrosoft.AspNetCore.OpenApiが提供さ れたため非推奨

Microsoft.AspNetCore.OpenApi • .NET 9以降OpenAPIドキュメント生成はこちらが標準 • Swagger UIは提供されていない • Swagger UIを使用したい場合は従来のSwashbuckleを組み 合わせて使うこともできる app.UseSwaggerUI(o => o.SwaggerEndpoint("/openapi/v1.json", "v1")); • お勧めはScalar.AspNetCore app.MapScalarApiReference();

Scalar https://learn.microsoft.com/ja-jp/aspnet/core/fundamentals/openapi/using-openapi-documents?view=aspnetcore- 9.0&WT.mc_id=%3Fwt.mc_id%3DDT-MVP-5004827#use-scalar-for-interactive-api-documentation

参考文献 • ASP.NET Core を使って Web API を作成する https://learn.microsoft.com/ja- jp/aspnet/core/web-api/?view=aspnetcore-9.0 • ASP.NET Core API アプリでの OpenAPI のサポート https://learn.microsoft.com/ja- jp/aspnet/core/fundamentals/openapi/overview?v iew=aspnetcore-9.0

おしまい おしまい