Swashbuckle (3) 顯示 webapi 方法上 xml 的摘要

設定在 swagger 頁面顯示的 xml 摘要資訊

環境：vs2017、.net framework 4.7、Swashbuckle 5.6.0

首先建立好一個 WebApi 專案和透過 Nuget 裝好 Swashbuckle，並且透過
http://localhost:xxxxx/swagger 能夠進到 Swashbuckle 的頁面。

本篇的目的在於讓 Api 上面的 xml 註解中的資訊出現在 swagger 的頁面上

在安裝好 swashbuckle 後開啟 App_Start 中的 SwaggerConfig.cs，這個檔案
應該在 Nuget 安裝好 Swashbuckle 時就自動產生。

取消 SwaggerConfig.cs 中的下面這一行的註解

    c.IncludeXmlComments(GetXmlCommentsPath());

在同一個 Class ( public class SwaggerConfig ) 下增加方法

   
 internal static string GetXmlCommentsPath()
 {
   //透過設定專案的屬性，設定在建置後生成 XmlDocument.xml，
   //此處是設定 Swagger 參考這份 xml
   return string.Format(@"{0}\App_Data\XmlDocument.xml",
   System.AppDomain.CurrentDomain.BaseDirectory); 
 }

圖上刪了很多原本是註解掉的部份

設定專案屬性，右鍵點專案 > 專案屬性 >　建置頁籤 > 輸出

有一個 XML 文件檔案，勾選並設定檔案的路徑，這個路徑需要和前一步設定

的 XML 路徑對應。

WebApi 的例子

  
/// <summary>
/// 人員
/// </summary>
public class Person
{
    /// <summary>
    /// 人員名稱
    /// </summary>
    public string Name { get; set; }
    /// <summary>
    /// 人員年紀
    /// </summary>
    public int Age { get; set; }
}

/// <summary>
/// 錯誤狀態
/// </summary>
public class ErrorStatus
{
    /// <summary>
    /// 狀態代碼
    /// </summary>
    public string StatusCode { get; set; }
    /// <summary>
    /// 狀態描述
    /// </summary>
    public string Description { get; set; }
}

 
public class PeopleController : ApiController
{
   /// <summary>
   /// 取得人員資料
   /// </summary>
   /// <remarks>
   /// 取得人員資料 api 的補充說明
   /// </remarks>
   /// <param name="id">人員 Id</param>
   /// <response code="200">成功</response>
   /// <response code="404">找不到</response>
   /// <response code="500">內部伺服器錯誤</response>
   [ResponseType(typeof(Person))]
   public IHttpActionResult Get(string id)
   {
      return Ok(new Person());
   }
}

如果設定了 [ResponseType(typeof(Person))] 因為他預設是在 Http Status 200
的時候所回傳的類別，所以需要同時設定 <response code="200">成功</response>
才會正常顯示 [ResponseType(typeof(Person))] 的部份

在傳入值或回傳值，切換到 Model 下時會顯示定義在 DataModel 上的 <summary> 訊息

執行專案，然後接下來進到 Swagger 頁面就可以看到 webapi 上設定的 xml 註解的資訊

在比較新版的 Swashbuckle 中，可以利用 SwaggerResponse 這個 attribute 來取代
<response code=""></response>

 
public class PeopleController : ApiController
{
  /// <summary>
  /// 取得人員資料
  /// </summary>
  /// <remarks>
  /// 取得人員資料 api 的補充說明
  /// </remarks>
  /// <param name="id">人員 Id</param>
  [SwaggerResponse(HttpStatusCode.OK, Description = "成功", Type = typeof(Person))]
  [SwaggerResponse(HttpStatusCode.NotFound, Description = "找不到")]
  [SwaggerResponse(HttpStatusCode.InternalServerError, Description = "內部伺服器錯誤", Type = typeof(ErrorStatus))]
  [ResponseType(typeof(Person))]
  public IHttpActionResult Get(string id)
  {
    return Ok(new Person());
  }
}