.Net Core 3.1 Web API × NSwagを用いて爆速でAPIドキュメントを提供する | cloud.config Tech Blog

この記事はFIXER Advent Calendar 2020 (https://adventar.org/calendars/5928) 15日目の記事です。

閲覧ありがとうございます。チーム開発でAPIを提供する場合、そのドキュメントをサクッと作れると生産性が上がると思います。今回は、.Net Coreで作成したWeb APIに対して、爆速でSwaggerを提供できるようにしてみます。

Web APIプロジェクトの作成

下記コマンドを実行します。現在.Net 5が正式リリースされていますが今回は.Net Core 3.1で進めます。

Bash$ dotnet new webapi -f netcoreapp3.1 -o Hoge

下記オプションを指定しています。

-f: ターゲットフレームワークを、.Net Core 3.1に指定します。
-o: 今回はHogeディレクトリを作って、そこにプロジェクトを格納してもらうようにしました。

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

GitHubのスター数が多いという理由で、NSwagを選択しています。
ちなみに.Net 5でWeb APIを作成すると初めからSwaggerが有効になっていますが、
そちらはSwashbuckleが使用されているみたいですね。

下記コマンドを実行します。

$ dotnet add package NSwag.AspNetCore

Startup.csの編集

Startup.csを、下記のように編集します。
追加する必要がある行の上に、コメントを入れてあります。

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // 下記1行を追加する。
    services.AddSwaggerDocument();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });

    // 下記2行を追加する。
    app.UseOpenApi();
    app.UseSwaggerUi3();
}

実行

アプリ実行後、/swaggerにアクセスするとSwaggerが表示されます。

例：

https://localhost:5001/swagger

画像は初めから実装されているAPIです

Swaggerのドキュメントに、APIの説明を追加する。

.csprojファイルを、下記のように編集します。

XML<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>

    <!-- 下記1行を追加する。 -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="NSwag.AspNetCore" Version="13.9.4" />
  </ItemGroup>

</Project>

また、Controllerのメソッドを、下記のように編集する。

// 下記4行を追加する。
/// <summary>
/// 天気予報を取得する。
/// </summary>
/// <returns></returns>
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
    var rng = new Random();
    return Enumerable.Range(1, 5).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = rng.Next(-20, 55),
        Summary = Summaries[rng.Next(Summaries.Length)]
    })
    .ToArray();
}

再度実行すると、下記のようにコメントが追加されます。

以上です。このブログを読んでくださった方の生産性が、少しでも向上すれば幸いです。