.NET Aspire で Linux 上に Swagger UI を追加する

Tim Corey

7m 24s

API エンドポイントをブラウザに手動で URL を入力してテストすることは、単純な確認には有効ですが、異なる HTTP 動詞やリクエストボディを持つルートが複数ある場合にはうまく機能しません。 Swagger UI は、すべてのエンドポイントを呼び出し、レスポンスを確認し、別のクライアントを作成したり curl フラグを記憶したりすることなく、パラメータを試すことができるインタラクティブなブラウザベースのパネルを提供します。

ビデオ"Adding Swagger UI to .NET Aspire on Linux"では、Tim Corey が前のエピソードから Tiny Ticket プロジェクトを引き継ぎ、既存の OpenAPI 構成の上に Swagger UI を追加します。 このプロセスは、3 行のコードと 1 つの NuGet パッケージで完了します。 その後、Tim は、マシンの再起動後に起動しなかったデータベース接続のトラブルシューティングを含む、Swagger インターフェイスを介したチケットエンドポイントの呼び出しを実演します。 C# on Linux のシリーズで API を構築している場合や、.NET プロジェクトで Swagger をセットアップするためのクイックリファレンスが必要な場合、このアーティクルではすべてのステップがカバーされています。

Swashbuckle NuGet パッケージのインストール

[0:38 - 1:35] TimはVS CodeでTiny Ticketプロジェクトを開き、APIサービスのProgram.csに移動します。 APIは既に前回のエピソードからGET /api/ticketsエンドポイントを持っていますが、呼び出すにはURLを手動で構築する必要がありました。 適切なテストインターフェースを追加するための第一歩は、Swagger UI パッケージをインストールすることです。

APIプロジェクトを右クリックし、"NuGetパッケージを追加"を選択し、Swashbuckle.AspNetCore.SwaggerUIを検索します。 Tim は、録画時点での最新バージョン (10.1.7) をインストールします。 インストール後、パッケージ参照がプロジェクトファイルに表示されます。他の依存関係は不要です。プロジェクトには、デフォルトの Aspire サービス構成を通して OpenAPI サポートが既に含まれているためです。

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Program.cs における Swagger UI の設定

[1:35 - 3:12] パッケージがインストールされると、設定はProgram.csの開発専用ブロックに記述されます。 プロジェクトは既にapp.MapOpenApi()が登録されており、実行時にOpenAPI仕様ファイルを生成します。Swagger UIはそのファイルの位置とエンドポイントグループのラベルを知っているだけで十分です。

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

SwaggerEndpoint呼び出しは、.NETが自動的に生成するOpenAPI仕様を指します。 2 番目のパラメータは、Swagger UI ドロップダウンに表示される名前です。 Tim は、これら 3 行が Swagger の全セットアップであると強調しています。UI をカスタマイズしたり、エンドポイントをグループ化したり、認証ヘッダーを追加したりするための設定を追加できますが、開発テストツールとしてはデフォルトで十分です。

一つ注意すべき点は、.NET 9 以降、新しい API プロジェクトにはデフォルトで Swagger が含まれていないことです。 Microsoft は、OpenAPI を標準として提供し、開発者が自分の好みの UI レイヤーを選択できるように、関心の分離を実現しました。 Swagger、Scalar、その他のツールはすべて同じ OpenAPI スペックファイルを使用するため、特定のビュアーに固定されることはありません。

Swagger インターフェイスの実行と検証

[3:12 - 6:07] 保存後、Tim は Run and Debug パネルを通じてプロジェクトを起動します。 Aspireダッシュボードがロードされ、APIサービスが実行中であることが表示されると、彼はAPIのURLに移動し、パスに/swaggerを追加します。

Swagger UI は"Ticket App API v1"というラベルでロードされ、利用可能なエンドポイントをリストします。 ルートエンドポイント（/api/ticketsはデータベースからチケットデータを返します。

Tim は、ルートエンドポイントで"試してみる"をクリックして実行します。 レスポンスには 200 ステータスと確認メッセージが返されます。 次に、彼は/api/ticketsエンドポイントに移動して、実行を押します。これがトラブルシューティングの始まりです。

最初の試行は、接続エラーで失敗します。"SQL サーバーへの接続を確立する際にネットワーク関連のエラーまたはインスタンス固有のエラーが発生しました。"データベースコンテナは、マシンの再起動後に起動していませんでした。 Tim は Portainer を開き、SQL サーバー Docker コンテナ を見つけて起動します。 コンテナの初期化が完了した後、再度 Swagger に戻り、リクエストを実行します。 今回は、データベースに保存されている 3 つのテストチケットが返される 200 のレスポンスが返ります。

このシーケンスは、実際のインフラストラクチャに対して統合テストを行うと、ユニットテストやモックデータでは見つからない問題が表面化するという実用的な指摘となります。 データベースコンテナは、起動時に自動開始が設定されていないため、再起動後の最初の API 呼び出しは、コンテナ状態を最初に確認しない限り失敗します。

次に来るもの: CRUD エンドポイント

[6:07 - 7:20] Tim はシリーズの次のエピソードのプレビューを行います。 Tiny Ticket APIは現在spTickets_GetAllストアドプロシージャにマップされています。 データベース内の残りのストアドプロシージャ（IDによる取得、挿入、更新、削除）はそれぞれ適切なHTTP動詞を持つ対応するAPIエンドポイントが必要です：取得にはDELETE。

彼は、各エンドポイントが同じパターンに従っており、実装が簡単であると指摘していますが、今後のビデオでは個別に詳細を解説する予定です。これにより、各部分が個別に参照しやすくなります。 シリーズを小さく集中したエピソードに分ける選択は、より長いビデオをスクラブすることなく必要なエンドポイントタイプに直接ジャンプできることを意味します。

結論

[7:20 - 7:24] Linux上で for .NET AspireプロジェクトにSwagger UIを追加するには、1つのNuGetパッケージとProgram.csに3行の設定が必要です。 OpenAPI スペックファイルは既にデフォルトの Aspire サービス設定によって生成されているため、Swagger はそのファイルへのポインターと表示名を必要とするだけです。 そこから、API のすべてのエンドポイントが別のクライアントを構築することなくブラウザを通じてテスト可能です。

Tim が再起動後に遭遇したデータベース接続の問題は、実用的な点を強調します: 開発スタックにコンテナが含まれている場合、API エンドポイントをテストする前にそれらが実行されていることを確認してください。 Swagger はその検証のための迅速なフィードバックループを提供します。

シリーズナビゲーション: このアーティクルは、Tiny Ticket アプリを構築するための C# on Linux シリーズの一部です。 前回: Linux 上で .NET Aspire を設定する。 次回: Get By ID エンドポイントを追加する。

例のヒント: Swagger以外のOpenAPIビューアを好む場合は、ScalarやRapiDocのようなパッケージをインストールし、同じ/openapi/v1.jsonエンドポイントを指してください。 スペックファイルは UI に依存しないため、API 設定を変更せずにビューワーを交換できます。

C# on Linux シリーズで API を構築する際のさらなる洞察を得るために、YouTube の彼の チャンネル で完全な ビデオ を視聴してください。