Magento2 開發 – 精確定義API回傳介面
上期我們詳盡示例了如何實作API回傳內容，其範例實作中的一環 – 定義介面（Interface），也就是回傳巢狀結構最繁複的一個環節，其實還隱藏了眉角，今天就跟大家進一步分享這些不易發現的細節！
首先，Magento原生對於API的支援，除了rest、soap這種協定(protocol)切換，還有透過Swagger工具，提供介面化可測試的API文件。我們可以直接在網站開啟Swagger API文件 http://{base-url}/swagger，
文件列出了網站目前提供的API端點，以及每個端點的使用方式、所需參數與回傳內容。
而官方的API文件 https://devdocs.magento.com/swagger/ ，就是使用Swagger轉換出來的
從Swagger API 文件可以觀察出，它對每個端點的要素都有清楚的規格說明，甚至給出範例內容。可以想見，要做到這份API文件的轉換，Magento勢必要提供每一支API的詳細資訊。
接著我們回到上次API回傳的實作例子，客製端點 rest/V1/astralweb/example/test
以單筆資料的範例實作，在Swagger文件顯示沒問題！
但在回傳多筆資料的實作範例中，卻會得到如下的的畫面
進一步追查錯誤訊息，得到『The “" class doesn’t exist and the namespace must be specified. Verify and try again.』。
還記得實作範例中所定義的API介面嗎，我們告訴程式回傳陣列值，但由於Swagger文件會明確給出回傳內容的規格，因此僅定義資料類型為陣列（多筆資料）是不夠的，必須更精確的給出每筆資料內容的定義，上述錯誤訊息，就是提示我們需要明確指定回傳什麼類別的陣列。
精確的API介面的描述會是這樣
回傳內容也要做對應的調整
如此修正，Swagger文件就能順利產生囉!
若每筆資料有巢狀結構，則需參照上回的單筆巢狀範例，依樣一層一層個別定義它的介面。Swagger文件的細節內容，就是透過解析這些介面所含資訊，將之轉譯成使用者易於解讀的規格描述。因此當我們所定義的介面不夠詳盡，它就會無法轉譯文件而回應錯誤。
另外要提醒的是，由於回傳介面是定義在註解，也就是說，轉譯時讀的也是註解。因此即使在該檔案我們使用 use AstralWeb\Example\Api\Data\TestInterface as ExampleTestInterface 的方式賦予別名，也不可以將別名使用在回傳定義上，畢竟該別名只有效在該檔案，而非執行轉譯的那支檔案。回傳定義一定要用完整包含命名空間(namespage)的介面名稱，否則轉譯時會找不到該介面或抓到錯誤的介面。
講到這，大家可能會有個疑問，既然這些細節會影響Swagger文件的產生，為什麼未精確定義介面的API仍然可以正常使用，沒有回應錯誤或給予任何警示呢？這樣的疑問也許只有Magento開發團隊的成員可以解答，而筆者就自己的觀點自己來看，作為一個開發者，開發過程有時為了便利，難免會有暫時性的測試用程式，如果Swagger只是一種輔助而非核心之必要功能，甚至有時在安全考量下，為了不對外暴露API內容會關閉該模組，但基於他功能上所需的開發成本並不小：想想為了建置暫時性可變動的測試端點，卻要繁瑣的建置異動那些定義，也算得上是開發不便了吧！那麼今天就跟大家分享到這，大家不妨檢查一下自己網站的Swagger文件是否正常運作，我們下回再見囉！
如果有您有更多疑問可以詢問我們，未來會撰寫更多電商網站相關文章，您想知道什麼嗎？
歡迎在下方留言給我們。或追蹤我們的粉絲專頁、Instagram，以及訂閱我們的電子報，就不會錯過最新文章喔！
我要留言