The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享

如何在 ASP.NET MVC 4 專案加上 Web API 與 API 說明頁面

ASP.NET Web API 功能強大,可很便利的設計出以 REST 為風格的 API 介面 (RESTful APIs),且早與 ASP.NET MVC 專案整合在一起。但是當 API 越寫越多時,如果沒有一個好個 API 文件或程式碼範例輔助,也很有可能會演變成一場災難。這篇文章,主要是撰寫如何在一個完全沒有 ASP.NET Web API 的專案中,加入新的 ASP.NET Web API 控制器 ( ApiController ) 並自動產生 API 文件的步驟。

§ 先在基礎 ASP.NET MVC 專案上新增 ASP.NET Web API 的 API 控制器

我們先建立好一個 ASP.NET MVC 4 Web 應用程式專案,並選用「網際網路應用程式」專案範本:

這時你可以看到專案中有 ASP.NET Web API 的相關路由設定,不過並沒有任何 Web API 的範例程式:

新增一個 API 控制器

image

如此一來,第一個簡單的 ASP.NET Web PI 範例程式即可建立完成

接著我們開啟 App_Start\WebApiConfig.cs 檔案,加入以下這行,讓我們的 ASP.NET Web API 永遠只回應 JSON 格式: ( 參考資訊: 如何讓 ASP.NET Web API 無論任何要求都回應 JSON 格式 )

GlobalConfiguration.Configuration.Formatters.XmlFormatter.SupportedMediaTypes.Clear();

然後透過 Google Chrome 瀏覽 http://localhost/api/Values 網址,就可以看到 API 的執行結果:

:我是在 Google Chrome 安裝 JSONView 擴充套件,才會在顯示 JSON 結果時自動格式化的。

 

§ 替 ASP.NET Web API 的 API 控制器加上註解

我們先為 API 控制器加上 XML 註解,直接在類別上方輸入三條斜線 ( /// ) 就會自動產生 XML 註解範本

再替每一個 API 中的方法,加上各自的 XML 註解,大致結果如下:

 

§ 產生專案的 XML 文件檔案

修改方案總管中的「專案屬性」

切換到「建置」頁籤,再勾選「XML 文件檔案」

預設的 XML 文件檔案會儲存在 bin\ 目錄下,請把內容改成 App_Data\XmlDocument.XML 這個路徑與檔名,之後才能讓 ASP.NET Web API 的說明頁面讀取到這個檔案。

最後執行 建置專案 ( F6 ) 就會自動在 App_Data 目錄下產生 XmlDocument.XML 檔案,而且每次建置都會自動更新此 XML 文件。

 

 

§ 建立 ASP.NET Web API 的說明頁面

我們可以透過 NuGet 安裝 Microsoft.AspNet.WebApi.HelpPage 套件,不過你若要安裝 ASP.NET MVC 4 內建的 ASP.NET Web API ( v1 ) 相容的 HelpPage 版本,必須安裝舊版的 HelpPage  套件

安裝舊版套件需要透過套件管理器主控台才能執行安裝命令,如下指令與圖示:

Install-Package Microsoft.AspNet.WebApi.HelpPage -Version 4.0.30506

安裝的過程,它會自動幫你安裝一個名為 HelpPage 的 MVC 子網站 ( Area )

最後,我們開啟 Areas/HelpPage/App_Start/HelpPageConfig.cs 進行設定,把第一行註解取消,即可自動讀入 API 控制器所設定的那些 XML 文件。

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

其重點還是在上述陳述式的路徑與檔名必須正確:

"~/App_Data/XmlDocument.xml"

大功告成!

 

最後,我們測試一下,直接瀏覽到 http://localhost/Help 網址,即可顯示含有註解的 API 說明網頁。

連接到其中一個 API 內頁,還會看到參數的說明,以及回應的 JSON 格式範例:

如果你想修改回應的範例文字,還可以修改 Areas/HelpPage/App_Start/HelpPageConfig.cs 檔案,以下提供幾個常見範例:

  • 清空所有 application/xml, text/xml 媒體類型的範例:
    config.Formatters.XmlFormatter.SupportedMediaTypes.Clear();
  • 提供自訂型別的範例格式: ( 如下程式的 UserProfile 則為我的自訂型別回應 )
    config.SetSampleObjects(new Dictionary<Type, object>
    {
    {typeof(string), "範例字串"},
    {typeof(IEnumerable<string>), new string[]{"範例 1", "範例 2"}},
    {typeof(UserProfile), new UserProfile() { UserId = 1, UserName = "保哥" }}
    });
  • 針對 ValuesController 的 Get 動作,並且帶入 id 參數,且回應內容類型是 image/png 的情況下,以圖片來當成回應的範例 ( ImageSample )  :
    config.SetSampleResponse(new ImageSample("/images/orderedList0.png"), 
    new MediaTypeHeaderValue("image/png"), "Values", "Get", "id");

 

相關連結