文章彙整

Magento2 開發 – 精確定義API回傳介面

Astral WebBy Astral Web 1 month agoNo Comments
首頁  /  Magento  /  Magento-2  /  Magento2 開發 – 精確定義API回傳介面

上期我們詳盡示例了如何實作API回傳內容,其範例實作中的一環 – 定義介面(Interface),也就是回傳巢狀結構最繁複的一個環節,其實還隱藏了眉角,今天就跟大家進一步分享這些不易發現的細節!

首先,Magento原生對於API的支援,除了restsoap這種協定(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,以及訂閱我們的電子報,就不會錯過最新文章喔!

想學習更多Magento設定嗎?請見:Magento教學導覽

以上內容由Astralweb 歐斯瑞編寫製作

 000

推薦文章

Categories:
  Magento-2MagentoMagento開發

留下回應

你的電子郵件地址不會被公開.

請到您的信箱確認,即可完成訂閱。