關於PostMan
PostMan是我在《ASP.NET MVC 4網站開發美學》第七章ASP.NET Web API裡介紹的兩個工具之一，它可以快速進行Web API的測試，不管是HTTP GET/POST/PUT/DELETE/PATCH…等方法或檔案上傳等都難不到它。但我們在測試Web API方法的過程裡，經常會發生一種不必要的錯誤，那就是打錯字或選錯HTTP動詞，明明就是”api/files“，老是打成”/files“，不然就是忘了改測試的HTTP動詞，這時就可以利用PostMan的Collections功能來預防與管理。
PostMan Collections功能
限制：它只能在Google Chrome裡使用。請透過Chrome Web Store來搜尋安裝「PostMan - REST Client」。
當我們不斷在PostMan輸入測試的API方法之後，左方會出現History清單，清單可以幫助我們快速執行重覆的API方法測試。
可是當清單一長，還是有不易選擇的問題，這時就可以在常用的API方法下將此測試方法加入Collection，只需要按【Add to collection】按鈕即可。
這樣就可以把常用的測試API方法分門別類整理好，以後需要測試時也只需要進來Collections頁籤裡點選執行測試。可以說是花一次功可重覆利用的好功能。
匯出ASP.NEt Web API公開的API方法給PostMan
PostMan的Collections除了手動建立外，也支援「匯入, Import」的功能，預設支援JSON格式的Collection資料。
一、PostMan資料格式：
''' <summary>
''' 建立PostMan測試項目所需資料格式
''' </summary>
''' <remarks>提供PostmanCollection使用</remarks>
Public Class PostmanRequest
Property collectionId As Guid
Property id As Guid
Property name As String
Property description As String
Property url As String
Property method As String
Property headers As String
Property data As String
Property dataMode As String
Property timestamp As Long
End Class
以上就是PostMan所需要的資料格式。
二、PostMan資料整理為一分Collection物件：
Imports System.Collections.ObjectModel
''' <summary>
''' Postman所需資料格式
''' </summary>
''' <remarks>最後會轉換為JSON提供Postman使用</remarks>
Public Class PostmanCollection
Property id As Guid
Property name As String
Property timestamp As Long
''' <summary>
''' 集合裡收集API方法，以建立Postman的測試方法項目
''' </summary>
Property requests As Collection(Of PostmanRequest)
End Class
這樣想，以Northwind資料庫為例，一個ProudctsController裡會有Get/Post/Put/Delete/Patch最少5個方法，所以一個Collection裡一個ProductsController收集出來會有五筆PostmanRequest資料。
三、收集所有已公開的API方法，匯出給PostMan
Imports System.Collections.ObjectModel
Imports System.Net
Imports System.Net.Http
Imports System.Web.Http
Imports System.Web.Http.Description
<ApiExplorerSettings(IgnoreApi:=True)>
Public Class PostmanController
Inherits ApiController
''' <summary>
''' 產生Postman Collection所需的JSON格式，以方便匯入API方法給Postman，讓開發人員快速測試。
''' </summary>
Public Function GetPostman() As HttpResponseMessage
' Configuration: 取得或設定目前 System.Web.Http.ApiController 的 System.Web.Http.HttpConfiguration。
' Properties: 取得與此執行個體相關的屬性。
' GetOrAdd: 如果索引鍵不存在，則將索引鍵/值組加入至 System.Collections.Concurrent.ConcurrentDictionary(Of TKey, TValue)。
Dim collection As PostmanCollection = TryCast(Configuration.Properties.GetOrAdd("postmanCollection",
Function(x)
Dim requestUri = Request.RequestUri
' scheme: http
' host: localhost
' port: your port
' HttpContext.Current.Request.ApplicationPath: /
' baseUri = http://localhost:port/
Dim baseUri As String = requestUri.Scheme & "://" & requestUri.Host & ":" & requestUri.Port & HttpContext.Current.Request.ApplicationPath
Dim postManCollection As New PostmanCollection()
postManCollection.id = Guid.NewGuid()
' 可自訂名稱
postManCollection.name = "Web API Products Service"
postManCollection.timestamp = DateTime.Now.Ticks
' 重要，存放測試項目的集合
postManCollection.requests = New Collection(Of PostmanRequest)()
' 一一提取出公開API的資訊，然後加入集合
For Each apiDescription In Configuration.Services.GetApiExplorer().ApiDescriptions
' .collectionId : 指定父Collection是誰(看Postman的結果清楚了)
' .method : HTTP Method
' .description : 如果你的API方法有撰寫註解的好習慣
' .baseUri : http://localhost:port/
' apiDescription.RelativePath 會取得如 /api/Products
Dim request As PostmanRequest = New PostmanRequest() With {
.collectionId = postManCollection.id,
.id = Guid.NewGuid(),
.method = apiDescription.HttpMethod.Method,
.url = baseUri.TrimEnd("/") & "/" & apiDescription.RelativePath,
.description = apiDescription.Documentation,
.name = apiDescription.RelativePath,
.data = "",
.headers = "",
.dataMode = "params",
.timestamp = 0
}
' 加入集合
postManCollection.requests.Add(request)
Next
Return postManCollection
End Function), PostmanCollection)
' 以JSON回傳集合結果
Return Request.CreateResponse(Of PostmanCollection)(HttpStatusCode.OK, collection, "application/json")
End Function
End Class
重要內容我都有打註解，自己看吧。如果你不希望API方法被匯出，請使用和Help Page一樣的取消方式，指定<ApiExplorerSettings(IgnoreApi:=True)>屬性。
選擇「匯入」，可選擇URI給PostMan或將取得JSON格式資料另存新檔，以檔案方式匯入。檔案方式匯入也是一種不錯的方式，尤其是當你不想把匯出方法公開出去時，我們可以先取得JSON格式資料，進行客製化修改，例如，把Delete方法刪除，再把檔案交給其他測試者。
匯入成功後，可以看到Collections頁籤已經將公開API方法匯入。匯入的項目還已以利用右方的按鍵進行修改、分享、刪除等管理動作。
如果你的API方法有撰寫註解的好習慣，那麼和Help Page一樣，在測試畫面中會帶有說明文字。
沒有留言:
張貼留言
感謝您的留言，如果我的文章你喜歡或對你有幫助，按個「讚」或「分享」它，我會很高興的。