[Swagger] ASP.NET Core API x Swagger II

前回　ASP.NET Core API x Swagger　の続き。 前回はSwaggerをAPIプロジェクトに追加して表示するところまで見ました。今日はもう少し先を見てみます。

起動時の「Swagger」ページ表示指定

アプリケーションを起動したら、Swaggerのページを表示したい場合。
プロジェクトの起動ディレクトリーを指定する必要があります。デフォルトは作業ディレクトリーは/api/valueになっているので、プロジェクトを右クリック、プロパティ、デバッグブラウザー起動を空で指定します。

サマリー

各メソッドの利用方法を簡単に記載します。

/// <summary>
/// Redeem Coupon
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpGet("/Reddem/{id}")]
public IActionResult Redeem(string id)
{
　　return NoContent();
}

Swagger上にはこのように記載されます。

リマークス

/// <summary>
/// Redeem Coupon
/// </summary>
/// <remarks>
/// This is remarks
/// </remarks>
/// <param name="id"></param>
/// <returns></returns>
[HttpGet("/Reddem/{id}")]
public IActionResult Redeem(string id)
{
  return NoContent();
}

Swagger上にはこのように記載されます。

レスポンスが jsonである事を表記する

レスポンスがjsonであることを表記するには[Produces("application/json")]を指定します。

[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class CouponController : ControllerBase
{
  /// <summary>
  /// Redeem Coupon
  /// </summary>
  /// <remarks>
  /// This is remarks
  /// </remarks>
  /// <param name="id"></param>
  /// <returns></returns>
  [HttpGet("/Reddem/{id}")]
  public IActionResult Redeem(string id)
  {
    return NoContent();
  }
}

Swagger上にはこのように記載されます。

レスポンスタイプの表記

正常に処理されれば200と値を返すのですが、毎度正常なインプットもしくは処理がされるとは限りません、その際にどんな時どのようなレスポンスタイプがあるのか表記しておく必要があります。

ここでは正常処理200と入力値が空のときのレスポンスタイプ400があることを明記します。

/// <summary>
/// Redeem Coupon
/// </summary>
/// <remarks>
/// This is remarks
/// </remarks>
/// <param name="id"></param>
/// <returns></returns>
/// <response code="201">Returns text "hi"</response>
/// <response code="400">If id is null</response>
[HttpGet("/Reddem/{id}")]
[ProducesResponseType(201)]
[ProducesResponseType(400)]
public IActionResult Redeem(string id)
{
　　if (string.IsNullOrEmpty(id))
　　{
　　　　return NotFound();
　　}

　　return Content("Hi");
}