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 控制器
如此一來,第一個簡單的 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");
相關連結