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

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是預設路由位置,我們可以看到以下的效果:

asp.net web api swagger 1

第二步:提供資料源

這個步驟有一半前一篇一模一樣,就是好好撰寫你的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);
  }
 

重新執行你的專案。

asp.net web api swagger 2

小結

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

swagger group by httpmethod

沒有留言:

張貼留言

感謝您的留言,如果我的文章你喜歡或對你有幫助,按個「讚」或「+1」,我會很高興的。

无觅相关文章插件,迅速提升网站流量