ASP.NET Web API 文件產生器(2) - Swagger

前一篇，我們使用ASP.NET Web API範本內建的Help Page快速產出即時的Web API文件，不過在APP Service - API App我們可以發現，微軟在未來的API App範本使用另一個Swagger，接下來我們來看看如何在現有的ASP.NET Web API專案中導入使用Swagger。

在ASP.NET Web API整合Swagger

Swagger是100% Open Source的軟體，它不只能快速產生Web API文件(有好看的UI)，而且能直接透過JSON或YAML進行Web API的匯入與匯出，並且可以快速的對你的Web API進行測試，不論此Web API是在本機或是遠端。

• Swagger UI 你可以試著操作Swagger的界面。
• Swagger Editor 可以使用JSON或YAML進行Web API的定義描敘，你可以隨意修改看看即時效果。

使用Swashbuckle

Swagger在不同平台有各自實作，我試了文件中.NET的幾套實作，目前還有在發展與維護的好像只有Swashbuckle，最簡單的分別，它連OWIN環境都有整合進去了 :D。

第一步：安裝NuGet Package

這個步驟很簡單，如果你是在IIS環境，那麼安裝：

  Install-Package Swashbuckle
 

如果是在Self-Hosted環境，那麼安裝：

  Install-Package Swashbuckle.Core
 

在IIS環境的組態下，他會加入App_Start/SwaggerConfig.cs組態檔，確認一下.EnableSwagger與.EnableSwaggerUi沒有被註解。

現在你就能啟動專案，並在輸入http://localhost:{port}/swagger，/swagger是預設路由位置，我們可以看到以下的效果：

第二步：提供資料源

這個步驟有一半前一篇一模一樣，就是好好撰寫你的XML註解，然後匯出為「XML文件檔案」，到此為止請參考上一篇。

  /// 

  /// 取得所有學生資料
  /// 
  /// 取回所有學生資料
  /// Internal Server Error
  public IHttpActionResult Get()
  {
  }

  /// 

  /// 取得學生資料
  /// 
  /// 唯一名稱
  /// 經由唯一名稱取得單一學生資料
  /// Not found
  /// Internal Server Error
  public IHttpActionResult Get(string userName)
  {
  }

  /// 

  /// 新增一位學生
  /// 
  /// 學生 Model
  /// 新增一位學生
  /// Bad request
  /// Internal Server Error
  public IHttpActionResult Post(Student student)
  {
  }

  /// 

  /// 刪除一位學生
  /// 
  /// 唯一的名稱
  /// 刪除一位已存在的學生
  /// Not found
  /// Internal Server Error
  public HttpResponseMessage Delete(string userName)
  {
  }
 

這裡面有個比較少見的XML註解，<response code="???">，這段<response code="???">XML註解會反應到Swagger上。

接下來我們要把XML資料指定給Swashbuckle使用。開啟SwaggerConfig.cs，在.EnableSwaggerUi上面一點點有個c.IncludeXmlComments(GetXmlCommentsPath());註解，把它反註解，然後程式就會出錯？不是啦，我們必須實作GetXmlCommentsPath()這個方法。

  private static string GetXmlCommentsPath()
  {
      return string.Format(@"{0}\App_Data\ApiDocUseSwashbuckle.XML", System.AppDomain.CurrentDomain.BaseDirectory);
  }
 

重新執行你的專案。

小結

Swashbuckle提供的Swagger不論在設置上或使用上要比Help Page簡單許多，而且內建直接測試API的功能，也更方便，不像Help Page還要額外的安裝與設置才能整理為一套來使用。SwaggerConfig.cs裡還有許多組態可以設置，例如：c.GroupActionsBy(apiDesc => apiDesc.HttpMethod.ToString());可以讓一開始的API文件使用HttpMethod來分類。