匯出ASP.NET Web API公開API方法至PostMan Collections

關於PostMan

PostMan - REST Client

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測試圖

當我們不斷在PostMan輸入測試的API方法之後,左方會出現History清單,清單可以幫助我們快速執行重覆的API方法測試。

PostMan History清單

可是當清單一長,還是有不易選擇的問題,這時就可以在常用的API方法下將此測試方法加入Collection,只需要按【Add to collection】按鈕即可。

新增Collection

這樣就可以把常用的測試API方法分門別類整理好,以後需要測試時也只需要進來Collections頁籤裡點選執行測試。可以說是花一次功可重覆利用的好功能。

Collection頁籤

匯出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方法刪除,再把檔案交給其他測試者。

匯入Collection按鈕

匯入成功後,可以看到Collections頁籤已經將公開API方法匯入。匯入的項目還已以利用右方的按鍵進行修改、分享、刪除等管理動作。

匯入Collection畫面

如果你的API方法有撰寫註解的好習慣,那麼和Help Page一樣,在測試畫面中會帶有說明文字。

含說明文字的API測試方法

沒有留言:

張貼留言

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