ASP.NetCoreでSwaggerを使用する方法

多くの場合、APIのドキュメントを作成する必要があります。このドキュメントを作成するには、Swaggerを利用できます。Swaggerは、APIのUI表現を簡単に提供するために使用できるツールです。APIのSwaggerドキュメントを生成すると、APIメソッドの署名を表示したり、APIメソッドをテストしたりすることもできます。

Swashbuckleは、Swaggerドキュメントを生成するためのオープンソースプロジェクトです。この記事では、Swashbuckleを利用してRESTfulAPIのインタラクティブなドキュメントを生成する方法について説明します。

ASP.NetCoreプロジェクトを作成します

まず、VisualStudioでASP.NetCoreプロジェクトを作成しましょう。Visual Studio2017またはVisualStudio 2019がシステムにインストールされていると仮定して、以下に概説する手順に従って、VisualStudioで新しいASP.NetCoreプロジェクトを作成します。

  1. Visual StudioIDEを起動します。
  2. 「新しいプロジェクトの作成」をクリックします。
  3. [新しいプロジェクトの作成]ウィンドウで、表示されたテンプレートのリストから[ASP.Net CoreWebアプリケーション]を選択します。
  4. [次へ]をクリックします。 
  5. 次に表示される「新しいプロジェクトの構成」ウィンドウで、新しいプロジェクトの名前と場所を指定します。
  6. [作成]をクリックします。 
  7. [新しいASP.NetCore Webアプリケーションの作成]ウィンドウで、ランタイムとして.Net Coreを選択し、上部のドロップダウンリストからASP.Net Core 2.2(またはそれ以降)を選択します。
  8. プロジェクトテンプレートとして「API」を選択して、新しいASP.Net Core WebAPIプロジェクトを作成します。 
  9. ここではこれらの機能を使用しないため、[Dockerサポートを有効にする]チェックボックスと[HTTPS用に構成する]チェックボックスがオフになっていることを確認してください。
  10. 認証も使用しないため、認証が「認証なし」に設定されていることを確認してください。
  11. [作成]をクリックします。

これらの手順に従うと、VisualStudioで新しいASP.NetCoreプロジェクトが作成されます。この記事の後続のセクションでこのプロジェクトを使用して、ValuesControllerのSwaggerドキュメントを生成する方法を調べます。

ASP.NetCoreにSwaggerミドルウェアをインストールします

ASP.Net Coreプロジェクトが正常に作成された場合、次に行うべきことは、必要なNuGetパッケージをプロジェクトに追加することです。これを行うには、ソリューションエクスプローラーウィンドウでプロジェクトを選択し、右クリックして[NuGetパッケージの管理...]を選択します。NuGetパッケージマネージャーウィンドウで、パッケージSwashbuckle.AspNetCoreを検索してインストールします。または、以下に示すように、NuGetパッケージマネージャーコンソールを介してパッケージをインストールすることもできます。

PM>インストール-パッケージSwashbuckle.AspNetCore

Swashbuckle.AspNetCoreパッケージには、ASP.NetCoreのAPIドキュメントを生成するために必要なツールが含まれています。

ASP.NetCoreでSwaggerミドルウェアを構成する

Swaggerを構成するには、ConfigureServicesメソッドに次のコードを記述します。AddSwaggerGen拡張メソッドを使用してAPIドキュメントのメタデータを指定する方法に注意してください。

services.AddSwaggerGen(c =>

            {{

                c.SwaggerDoc( "v1"、新しい情報

                {{

                    バージョン= "v1"、

                    Title = "Swagger Demo"、

                    説明= "ValuesControllerのSwaggerデモ"、

                    TermsOfService = "なし"、

                    Contact = new Contact(){Name = "Joydip Kanjilal"、

                    メール= "[email protected]"、

                    Url = "www.google.com"}

                });

            });

以下に示すように、ConfigureメソッドでSwaggerUIも有効にする必要があります。

app.UseSwagger();

app.UseSwaggerUI(c =>

{{

   c.SwaggerEndpoint( "/ swagger / v1 / swagger.json"、 "v1");

});

参考までに、Startupクラスの完全なコードを次に示します。

Microsoft.AspNetCore.Builderを使用する;

Microsoft.AspNetCore.Hostingを使用する;

Microsoft.AspNetCore.Mvcを使用します。

Microsoft.Extensions.Configurationを使用します。

Microsoft.Extensions.DependencyInjectionを使用する;

Swashbuckle.AspNetCore.Swaggerを使用します。

名前空間SwaggerDemo

{{

    パブリッククラスのスタートアップ

    {{

        public Startup(IConfiguration configuration)

        {{

            構成=構成;

        }

        public IConfiguration Configuration {get; }

        public void ConfigureServices(IServiceCollection services)

        {{

            services.AddMvc()。SetCompatibilityVersion

            (CompatibilityVersion.Version_2_2);   

            services.AddSwaggerGen(c =>

            {{

                c.SwaggerDoc( "v1"、新しい情報

                {{

                    バージョン= "v1"、

                    Title = "Swagger Demo"、

                    説明= "ValuesControllerのSwaggerデモ"、

                    TermsOfService = "なし"、

                    Contact = new Contact(){Name = "Joydip Kanjilal"、

                    メール= "[email protected]"、

                    Url = "www.google.com"

                }

                });

            });

        }

        public void Configure(IApplicationBuilder app、

       IHostingEnvironment env)

        {{

            if(env.IsDevelopment())

            {{

                app.UseDeveloperExceptionPage();

            }

            app.UseMvc();

            app.UseSwagger();

            app.UseSwaggerUI(c =>

            {{

                c.SwaggerEndpoint( "/ swagger / v1 / swagger.json"、 "v1");

            });

        }

    }

}

Swaggerを使い始めるために必要なのはこれだけです。

ASP.NetCoreアプリのSwaggerUIを参照します

これで、アプリケーションを実行してSwaggerエンドポイントを参照する準備が整いました。Swagger UIは、以下の図1のように表示されます。SwaggerがHTTP動詞GET、PUT、POST、およびDELETEにさまざまな色を使用する方法に注意してください。図1に示す各エンドポイントは、SwaggerUIから直接実行できます。

コントローラのアクションメソッドでXMLコメントを作成します

ここまでは順調ですね。以前に生成されたSwaggerドキュメントには、XMLコメントはありませんでした。SwaggerドキュメントにXMLコメントを表示する場合は、コントローラーのアクションメソッドにそれらのコメントを書き込むだけです。

次に、ValuesControllerの各アクションメソッドにコメントを記述しましょう。これは、各アクションメソッドのXMLコメントを含むValuesControllerの更新バージョンです。

  [Route( "api / [controller]")]

    [ApiController]

    パブリッククラスValuesController:ControllerBase

    {{

        ///

        ///引数なしでアクションメソッドを取得します

        ///

        ///

        [HttpGet]

        public ActionResult 取得する()

        {{

            新しい文字列を返す[] {"value1"、 "value2"};

        }

        ///

        ///整数を引数として受け入れるアクションメソッドを取得します

        ///

        ///

        ///

        [HttpGet( "{id}")]

        public ActionResult Get(int id)

        {{

            「値」を返します。

        }

        ///

        ///データを追加するためのアクション後のメソッド

        ///

        ///

        [HttpPost]

        public void Post([FromBody] string value)

        {{

        }

        ///

        ///データを変更するためのアクションメソッドを配置します

        ///

        ///

        ///

        [HttpPut( "{id}")]

        public void Put(int id、[FromBody] string value)

        {{

        }

        ///

        ///アクションメソッドを削除します

        ///

        ///

        [HttpDelete( "{id}")]

        public void Delete(int id)

        {{

        }

    }

SwaggerでXMLコメントをオンにする

SwaggerはデフォルトでXMLコメントを表示しないことに注意してください。この機能をオンにする必要があります。これを行うには、[プロジェクト]を右クリックし、[プロパティ]を選択して、[ビルド]タブに移動します。[ビルド]タブで、[XMLドキュメントファイル]オプションをオンにして、XMLドキュメントファイルが作成される場所を指定します。

また、ConfigureServicesメソッドで次のコードを記述して、Swaggerドキュメントを生成するときにXMLコメントを含めるように指定する必要があります。

c.IncludeXmlComments(@ "D:\ Projects \\ SwaggerDemo \ SwaggerDemo \ SwaggerDemo.xml");

SwaggerでXMLコメントをオンにするために必要なのはこれだけです。

アプリの起動URLをSwaggerUIに設定します

アプリケーションの起動URLを変更して、アプリケーションの起動時にSwaggerUIが読み込まれるように指定できます。これを行うには、プロジェクトを右クリックして[プロパティ]を選択します。次に、[デバッグ]タブに移動します。最後に、図2に示すように、LaunchBrowserの値をswaggerとして指定します。

アプリケーションを再度実行してSwaggerURLに移動すると、下の図3に示すようなSwaggerUIが表示されます。今回は、各APIメソッドのXMLコメントに注意してください。

Swashbuckleは、API用のSwaggerドキュメントを生成するための優れたツールです。最も重要なのは、Swashbuckleの構成と使用が簡単なことです。Swaggerでできることは、ここで見た以上にたくさんあります。カスケードスタイルシートを使用してSwaggerUIをカスタマイズしたり、列挙値を文字列値として表示したり、APIのバージョンごとに異なるSwaggerドキュメントを作成したりできます。