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

8 分

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

Note

この演習を完了するには、ソースコードをローカルコンピューターにダウンロードします。ファイルをダウンロードしたら、解凍する必要があります。

ダウンロード: ASP.NET Core Web API アプリケーション。

画面の中央右にあるダウンロードボタンを選択します。
exercise.zip ファイルを解凍します。

Swagger ツールを追加する

Visual Studio を開き、ASP.NET Core Web API アプリを見つけます。
ソリューションエクスプローラーで、プロジェクトを右クリックし、[NuGet パッケージの管理] メニューを選択します。
NuGet パッケージマネージャーで、Swashbuckle.AspNetCore を検索します。パッケージを選択して、インストールします。

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

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

Startup.cs ファイルを開きます。
namespace InventoryManagement.ApiApp の行のすぐ上に次のディレクティブを追加します。
```
/* === using directive BEGIN === */
using Microsoft.OpenApi.Models;
/* === using directive END === */
```

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

    services.AddControllers();

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

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 === */
```
Note

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

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

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

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

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

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

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

続行

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

Swagger ツールを追加する

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

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

フィードバック

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