WebAPI真是個好物,可以自動依據Client端的需求將Server 端的物件產出XML或者JSON的內容,也可以支援OData的方式進行查詢。不過由於方式比較特別,呼叫的人如果沒有相關文件,可能會不知道該如何呼叫,該傳遞什麼樣的參數、什麼樣的json內容。而剛好,WebAPI有支援自動產出Help Page,自動將寫好的Web API產生相關的說明,還可以線上進行查詢。這樣讓我們開發的人員,可以專心的寫好我們的程式。這樣的方式真的太棒了。這一篇就來介紹怎麼樣產生WebAPI的Help Page。
緣起
WebAPI真是個好物,可以自動依據Client端的需求將Server 端的物件產出XML或者JSON的內容,也可以支援OData的方式進行查詢。不過由於方式比較特別,呼叫的人如果沒有相關文件,可能會不知道該如何呼叫,該傳遞什麼樣的參數、什麼樣的json內容。而剛好,WebAPI有支援自動產出Help Page,自動將寫好的Web API產生相關的說明,還可以線上進行查詢。這樣讓我們開發的人員,可以專心的寫好我們的程式。這樣的方式真的太棒了。這一篇就來介紹怎麼樣產生WebAPI的Help Page。
準備好WebAPI
首先,當然是要準備好我們的WebAPI,這部分有很多的資訊可以查詢,這裡就不再贅述。小喵就以之前寫好的Product的WebAPI來當作這次的範例。
啟動執行專案
當我們啟動執行我們寫好的專案,出現的畫面中,右上方有個API的地方可以按,點進去後就會進入WebAPI的說明頁
原來目前的WebAPI專案,早已經將WebAPI的說明,包在專案之中了
不過,再回頭看看我們的API,我們在寫API的時候,我們在程式裡面,會寫一些程式的註解,方便未來維護的人可以有個脈絡依循。像以下這樣:
''' <summary>
''' 傳回所有的商品資料
''' 支援OData查詢
''' </summary>
''' <returns>成功傳回Product物件集合資料</returns>
''' <remarks></remarks>
<Queryable>
Public Function GetValues() As IQueryable(Of ProductInfo)
Dim ProdObj As New ProductDAO
Dim oProds As List(Of ProductInfo) = ProdObj.GetAll()
Return oProds.AsQueryable
End Function
' GET api/products/5
''' <summary>
''' 依據傳入的id,查詢符合該ProductID的商品資料
''' </summary>
''' <param name="id">商品編號ProductID</param>
''' <returns>成功傳回商品資料</returns>
''' <remarks></remarks>
Public Function GetValue(ByVal id As Integer) As ProductInfo
Dim ProdObj As New ProductDAO
Dim oProd As ProductInfo = ProdObj.GetProdByID(id)
If oProd.ProductName = "" Then
End If
Return oProd
End Function
' POST api/products
''' <summary>
''' 依據傳入的產品資料oProd,新增產品資料
''' </summary>
''' <param name="oProd">從 Body 傳入產品資料</param>
''' <remarks></remarks>
Public Sub PostValue(<FromBody()> ByVal oProd As ProductInfo)
Dim ProdObj As New ProductDAO
Dim Rc As String = ProdObj.InsertProd(oProd)
End Sub
但是實際看顯示出來的Help Page中,並沒有將我們寫好的註解放在畫面中
這個部分就需要我們來做些設定,讓我們的註解可以顯示在Help Page中了
Help Page相關程式的位置
要去針對Help Page做修改,首先要知道這些程式碼放在哪個位置
他是存在專案中的【Area/Help】裡面
修改專案屬性,編譯產生XML文件
要讓Help Page讀取我們寫在程式裡面的說明,首先要讓他編譯的時候,產生XML的相關檔案,這部分在專案的屬性裡面,進行設定
修改HelpPageConfig
,需要修改一下放在【Area/HelpPage/App_Start/HelpPageConfig.vb】這個檔案
開啟這個檔案後,找到以下這個,本來註解掉的,取消註解
並且修改編譯時產生的XML檔案的路徑與位置
當我們幫專案編譯時,會產生專案名稱.dll與專案名稱.xml在【bin】的系統資料夾
這個專案的名稱是【tWebAPI_Help】所以要更改檔案路徑與檔名為【~/bin/tWebAPI_Help.xml】
修改後的程式如下:
重新編譯後,看看結果
我們修改後,將專案重新編譯,然後網頁重新整理,就可以看到Help Page已經抓到我們寫在程式上面的相關註解內容
點選API之後,看看結果畫面
可以看到,除了我們幫參數寫的說明已經放上來,並且依據我們傳入的來源告知資料是來自【body】還是【URI】
另外也很貼心的幫我們把要傳入的參數,產生了一個範例放出上來
這樣在測試的時候就可以很輕鬆地將範例複製,修改相關的值,然後進行測試
末記
WebAPI開發上不但簡單,連WebAPI的相關文件也都能夠簡單的產出,並且線上查詢。而且這部分功能就已經直接包在開發範本之中,只需做個小小的設定,就能夠幫我們把寫程式時同時寫好的一些說明,直接產出說明頁面,更貼心的幫我們生出傳遞參數的範本,或WebAPI GET後傳回的JSON範本。真是太方便了。有興趣的人可以再試試【HelpPageConfig】的其他設定。
特別用這篇筆記一下。也提供有需要的人做參考
^_^
以下是簽名:
- 歡迎轉貼本站的文章,不過請在貼文主旨上加上【轉貼】,並在文章中附上本篇的超連結與站名【topcat姍舞之間的極度凝聚】,感恩大家的配合。
- 小喵大部分的文章會以小喵熟悉的語言VB.NET撰寫,如果您需要C#的Code,也許您可以試著用線上的工具進行轉換,這裡提供幾個參考
Microsoft MVP Visual Studio and Development Technologies (2005~2019/6) | topcat Blog:http://www.dotblogs.com.tw/topcat |