演習 - Swashbuckle を使用して OpenAPI ドキュメントを作成する

この演習では、ASP.NET Core Web API アプリケーションに Swagger と Swagger UI を追加します。 Swagger ツールは、Web API を記述する OpenAPI ドキュメントの作成に役立ちます。

1. [生ファイルのダウンロード] ボタンを選択します。
2. exercise.zip ファイルを解凍します。

Swagger ツールを追加する

1. Visual Studio を開き、ASP.NET Core Web API アプリを見つけます。

   

2. ソリューション エクスプローラーで、プロジェクトを右クリックし、[NuGet パッケージの管理] メニューを選択します。

   

3. NuGet パッケージ マネージャーで、Swashbuckle.AspNetCore を検索します。 パッケージを選択して、インストールします。

   

   これで NuGet パッケージがインストールされました。 [NuGet パッケージ マネージャー] タブを閉じます。

OpenAPI ドキュメントを生成するように Swashbuckle を構成する

1. Startup.cs ファイルを開きます。

   

2. namespace InventoryManagement.ApiApp の行のすぐ上に次のディレクティブを追加します。

   /* === using directive BEGIN === */
   using Microsoft.OpenApi.Models;
   /* === using directive END === */
   

3. ConfigureServices(IServiceCollection) メソッド内のすべてのコードを、次のコードに置き換えます。

       services.AddControllers();
   
       /* === SwaggerGen BEGIN === */
       services.AddSwaggerGen(c =>
       {
           c.SwaggerDoc("v1", new OpenApiInfo { Title = "Inventory Management", Version = "v1" });
       });
       /* === SwaggerGen END === */
   

4. Configure(IApplicationBuilder, IWebHostEnvironment) メソッド内で、if (env.IsDevelopment()) 条件ステートメントを見つけて、そのステートメントの上のすべてを次のコードに置き換えます。

       /* === SwaggerUI BEGIN === */
       app.UseSwagger(c =>
       {
           c.PreSerializeFilters.Add((swagger, httpReq) => {
               var server = new OpenApiServer() { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" };
               swagger.Servers = new List<OpenApiServer>() { server };
           });
       });
       app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "InventoryManagement.ApiApp v1"));
       /* === SwaggerUI END === */
   

   メモ

   Swagger エンドポイントを有効にする場合、開発環境に限ることは非常に重要です。 そうしないと、API が一般に公開される可能性があります。

   ASP.NET Core Web API アプリへの OpenAPI ドキュメント機能のアクティブ化が完了しました。 Startup.cs ファイルを保存します。 変更箇所は次のスクリーンショットのようになります。

   

OpenAPI ドキュメント ファイルを生成する

1. Visual Studio の上部中央にあるデバッグ ボタンを選択します。

   

   自動的に Web ブラウザーが開き、Swagger UI ページが表示されます。

   

   404 エラーページが表示される場合があります。 この場合は、ブラウザーのアドレス バーに https://localhost:<port_number>/swagger の URL を入力します。 たとえば次のスクリーンショットでは、URL は https://localhost:44371/swagger です。

   

2. リンクを選択して、OpenAPI ドキュメント ページを開きます。

   

3. OpenAPI ドキュメントは、その場でレンダリングされます。

   

これで、ASP.NET Core Web API アプリで OpenAPI ドキュメントを生成する準備ができました。