今回はNSwagを使って .NET 9のASP.NET Core Web APIでSwagger UIを作成する方法をご紹介します。
目次
.NET 9のWeb APIテンプレートではSwagger UIが作成されない
Visual Studio 2022で「ASP.NET Core Web API」のテンプレートからWeb APIを作成し実行すると、 .NET 8までは以下のようなSwagger UIの画面が自動生成され、アプリケーションの中でAPIの実行テストが可能でした。
.NET 9では同様に「ASP.NET Core Web API」のテンプレートからWeb APIを作成し実行しても、OpenAPIのドキュメントが生成されるのみでSwagger UIの画面は自動生成されません。
「Web APIのURL/openapi/v1.json」にブラウザからアクセスすると、OpenAPIのJSONドキュメントが確認できます。
ASP.NET Core Web APIのプロジェクトテンプレートでは「Swashbuckle」というライブラリを使用してSwagger UIを生成していましたが、メンテナンスが積極的に行われないことを理由に、マイクロソフト社は .NET 9でプロジェクトテンプレートからSwashbuckleを削除し、OpenAPIのドキュメントのみを提供するようにしました。
Swagger UIが自動生成されなくなっただけで、Web APIは問題なく実行できますし、Postmanなど代替のテスト手段もありますが、やはりアプリケーションの中だけでAPIの動作確認ができるSwagger UIがあったほうが便利なので、今回は別のライブラリを使って .NET 9でSwagger UIを作成できるようにしてみます。
NSwagでSwagger UIを作成する
NSwagとは
NSwagは .NETアプリケーションでWeb APIを開発する際に、OpenAPI（Swagger）仕様を活用してAPIクライアントやAPIドキュメントを生成するためのツールで、先ほどのマイクロソフト社のポストの中でも代替手段として紹介されています。
NSwagをASP.NET Core Web APIに組み込む
NSwagを使用してSwagger UIを生成する方法は簡単です。 .NET 9の「ASP.NET Core Web API」のプロジェクトテンプレートからWeb APIを作成し、作成されたプロジェクトを右クリック⇒「NuGetパッケージの管理」から、「NSwag.AspNetCore」のパッケージをインストールします。
※ プロジェクト作成時に「OpenAPIサポートを有効にする」のオプションにチェックを入れて作成してください。
次に「Program.cs」を以下のように追記します。オプションの「DocumentPath」で元となるOpenAPIドキュメントのパスを指定します。
・・・（中略）・・・
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.UseSwaggerUi(options =>
{
options.DocumentPath = "openapi/v1.json";
});
}
・・・（中略）・・・上記を設定後、デバッグ実行し「Web APIのURL/swagger」にアクセスすると、Swagger UIが自動生成されます。
アプリケーションの中でAPIの実行をテストできます。
ASP.NET Core Web APIでのNSwagの使用方法はマイクロソフト社の以下のページもご参考ください。
さいごに
今回は .NET 9のASP.NET Core Web APIのプロジェクトテンプレートでNSwagを使用し、Swagger UIを自動生成する方法をご紹介しました。
メシウスは .NETでの業務アプリケーション開発を支援するライブラリを多数提供しています。
無償のトライアル版や、ブラウザ上で手軽に試せるデモアプリケーションも公開しているので、こちらも是非ご覧ください。