通過Swagger進行API設計,與Tony Tam的一次對話

2018-02-24 15:47 更新

要找到Tony Tam真不是一件容易的事,他總是日理萬機難以抽身。人們對于Tam的了解多數(shù)來自于在他的影響下出現(xiàn)的Swagger,這是目前最流行的一種Web API規(guī)范框架。Tam同時也是Reverb的創(chuàng)始人,這是一家進行內容分析與推薦業(yè)務的公司。他還是Wordnik的奠基人之一,這是世界上最大的在線英文辭典。自從他在加州大學圣塔芭芭拉分校與圣塔克拉拉大學就讀以來,他已經參與了數(shù)家公司的創(chuàng)立。他甚至還擁有一項基于內容獲取創(chuàng)建用戶檔案技術的專利技術。如今Reverb已經被NDN(newsinc.com)所收購,而Tam正在新興技術部副總裁這個新職位上忙得不亦樂乎。

這段時間對于Swagger框架來說也是一個繁忙的季節(jié),在Swagger的開放工作小組(自2014年5月成立)的不懈努力下,Swagger 2.0終于在2014年9月正式發(fā)布了。我們的采訪是在2015年3月進行的,此時距2.0的工作啟動還不足一年。此外,不久之前Reverb剛剛宣布Swagger規(guī)范未來的發(fā)展將轉交SmartBear,這是一家位于馬薩諸塞州的軟件工具公司。

人們對于近期的一些事件還記憶猶新,因此我們的對話將從2009年Swagger框架啟動時說起。

Mike Amundsen**:Swagger API框架原本并不是一個公開的項目,而是在Reverb(當時還稱為Wordnik)內部開發(fā)的一個項目,這可能會讓人們感到吃驚。你能為我們介紹一下Swagger項目剛剛成立時的一些情況嗎?**

Tony Tam:啟動Swagger這個項目的目的是克服當時在Wordnik的工作中所遇到的一些真實的挑戰(zhàn)。當時我們正在創(chuàng)建REST API,由我們的付費客戶進行調用。在公司內部,我們?yōu)橄到y(tǒng)打造了一個統(tǒng)一的API接口,希望根據(jù)我們與每個客戶之間的協(xié)定為他們開放權限。也就是說在文檔中只記錄他們有權限使用的操作。此外,客戶還要求我們向其提供原生的SDK。

Mike**:因此為了解決創(chuàng)建大量的自定義接口與文檔的麻煩,你們就設計了Swagger**是嗎?

Tony:是的,而且我也很討厭重復地做一些完全相同的事。我們當時想到了一個點子,就是為我們的REST API創(chuàng)建一個泛用的JSON模型,它能夠反映出調用者有權限進行哪些操作。它成為了我們的代碼生成器的輸入模型。之后,在我們辦公室中有一位非常聰明的開發(fā)者指出,我們應當如何使用這一模型以打造一個交互式文檔的UI,它后來就成為了Wordnik開發(fā)者網站。正是通過JSON模型與交互式文檔的概念相結合,才有了我們如今稱為Swagger這一框架的出現(xiàn)。

Mike**:那么,Swagger**又是怎樣一步一步成為如今被廣泛使用的一個面向公眾的工具呢?

Tony:在我們將交互式UI發(fā)布至http://developer.wordnik.com之后,我們對于這一項目的興趣也是水漲船高,并最終將它的UI、服務端集成以及代碼生成部分全部進行了開源。

這個項目的初始目標是處理一些現(xiàn)實世界中遇到的挑戰(zhàn),雖說它目前的發(fā)展已經遠遠超越了它起初的模樣,但核心的思想依然是為API定義一個一致的、可預測的模型。

Mike**:你從2009年開始從事Swagger的開發(fā),而Swagger 2.0版本剛剛在2014年秋季發(fā)布。發(fā)布新版本的主要動力是什么,Swagger在新版本中又迎來了哪些變化呢?**

Tony:經過了多年的參與之后,你肯定已經清楚哪些方式行得通、哪些行不通。在之前版本中有一些結構化方面的問題,它會造成大量的支持問題,此外我們也希望在Swagger規(guī)范中對JSON格式的schema進行更好的支持。我們還希望讓定義變得更簡潔,并且便于在建模工具中進行編輯。

Mike**:那么,對于Swagger用戶來說,“2.0”是一個破壞性的版本嗎?**

Tony:我們在過去三年間發(fā)布了Swagger的1.0、1.1與 1.2版本,它們與原始的設計相比只有一些小幅度的改進。而這一次,我們借此機會對Swagger規(guī)范進行了一次較大的改動。

當然,我們在每個版本中都盡量做到讓升級工作變得更簡單。即使Swagger 2.0中有如此多的變化,但服務端工具、UI與代碼生成模板依然具有良好的兼容性。一般情況下只需對依賴進行相應的升級就可以了。

Mike**:Swagger 2.0中的一個新特性是允許定義擴展。為什么要加入這一特性?是否能夠舉例說明一下API開發(fā)者應當如何使用這些擴展?**

Tony:這個特性推動的動力來自于以下幾點。

首先,我們并不想把所有可能的特性都塞到這個規(guī)范中去。先前曾有人建議將調用頻度限制的功能也加到規(guī)范中,但這一特性很難實現(xiàn)泛用性,由于大多數(shù)用戶都不會在意這一特性,因此我們不想因為它而污染了這一規(guī)范。

其次,我們從Swagger的最初幾個版本中學到了一個經驗:如果沒有一種簡單而健壯的校驗機制,那么很容易就會寫出無效的規(guī)范。我們最終選擇了JSON Schema校驗工具,并將這一工具直接加入Swagger-UI項目中。這是我們的工具集中非常重要的一部分,它能夠幫助開發(fā)者編寫有效的Swagger定義。

要從規(guī)范中移除結構化的限制,同時要保留一種健壯的校驗工具,實現(xiàn)這一點非常困難。我們所選擇的方式是在規(guī)范中通過使用一種擴展前綴獲得更大的靈活性,開發(fā)者能夠讓Swagger產生更大的實用性。有些非常實用的擴展有可能會在下個版本的Swagger中“升級”為標準特性。

Mike**:Swagger 2.0的發(fā)布似乎得到了來自社區(qū)的極大影響,包括大量的變更請求與新特性。你如何決定在2.0中加入哪些變更呢?**

Tony:Swagger 2.0規(guī)范中包含了所有我們認為有意義的特性,這個項目不是由時間線或某個特性集所驅動的。我們獲取了大量有價值的建議并認真聆聽。最終,我們基于規(guī)范的核心目標做出決策,而不是嘗試同時解決所有人的問題,后者只會使你的項目變成一個大泥巴球。

Mike**:有一個特性請求最終沒有出現(xiàn)在2.0版本中,即對于超媒體描述的支持。但在Github上,這一[問題](https://github.com/swagger-api/swagger-core/issues/97#event-159248864)處于已關閉狀態(tài),并描述為“不在設計考慮中”。超媒體在API設計的地位正在不斷提高,為什么你認為它不應出現(xiàn)在2.0版本中呢?你認為它有可能會出現(xiàn)在今后的版本中嗎?**

Tony:這個提交信息本身已經說得很清楚了,Swagger的這個版本并非是為了超媒體而存在的,或許它在某種程度上確實有存在的意義,但即使加入對Hypermedia的支持,也無法實現(xiàn)Swagger目前的任何目標?;蛟S它們之間確實有些格格不入,但我對此也不是非常確定。

Mike**:雖然Swagger出現(xiàn)至今還不到5年時間,但它在Web API的開發(fā)者中已經有了大量的粉絲。它的足跡似乎比其它的一些API設計更為深刻,包括WSDL、WADL、AtomSvc以及其它。你認為產生這一情況的原因是什么?是什么原因讓Swagger得到了如此[廣泛](http://www.javaworld.com/article/2607177/java-app-dev/swagger-aims-to-become-the-de-facto-standard-for-apis.html)的應用。**

Tony:在我看來,Swagger能夠得到這樣的成功,其背后有一些關鍵的因素。首先,它確實解決了一些常見的問題。你是否能夠以一種簡便的方式為老板展示你的API?你怎樣讓客戶試用它?Swagger UI能夠幫助描述這個API的功能,以及它的運作方式。

其次,Swagger規(guī)范本身足夠簡單,開發(fā)者在每一種主流的編程語言中都編寫過對它的集成。像Swagger Inc.這樣的企業(yè)能夠負責整個API的工具鏈,而使用我們的工具的開發(fā)者已經不下一萬,他們編寫了各種不同的集成方式。能夠跨語言以及跨框架對Swagger的發(fā)展非常重要。

最后一點,Swagger的成長經歷與眾不同,它不是通過市場宣傳,或是在某個充斥著flash的網站上展示各種logo而興起的。它的流行完全來自于開發(fā)者這一草根階層自發(fā)的支持。

Mike**:在撰寫本文時,目前最常用的三個API描述框架應當要屬Swagger、RAML和Apiary Blueprint了。你認為Swagger**與其它兩種格式相比有什么優(yōu)勢?開發(fā)者會基于哪些因素而選擇其中一種格式?

Tony:我在這里可以提幾點。這些規(guī)范的功能有著明顯的不同之處,想要同時支持這三種規(guī)范而又不失通用性是不太可能的,因為你無法將某種規(guī)范簡單地轉換成另一種。這就像要你設計一種適合任意尺寸的汽車防塵罩,能夠同時適合你的保時捷與房車一樣不現(xiàn)實。

Swagger在所有這些描述格式中的結構是最多的,它的核心目標是能夠為強類型語言實現(xiàn)操作與模型的描述,這也意味著我們能夠在API中提供足夠的元數(shù)據(jù)信息,以生成原生的C++客戶端。

Mike**:那么,Swagger是不是一種“嚴格”的格式,讓開發(fā)者能夠通過它學到創(chuàng)建API的“正確方式”呢?**

Tony:Swagger并沒有讓開發(fā)者強制使用一種單一的工作流,它并不強制你選擇自頂向下或是自底向上式的編碼風格。對于其它格式來說,這確實是一個不可避免的抉擇,因為它們對于工作流有嚴格的規(guī)定。

我想大多數(shù)開發(fā)者在選擇描述格式時都會考慮到他們所使用的編程語言。如果某種格式沒有符合你的編程語言的實現(xiàn),你很可能會另請高明。

Mike**:有一句話你經常[掛在嘴邊](http://www.javaworld.com/article/2607177/java-app-dev/swagger-aims-to-become-the-de-facto-standard-for-apis.html),在創(chuàng)建Swagger時,你希望能夠避免“CORBA問題”。CORBA問題指的是什么?你在創(chuàng)建Swagger時又是怎樣避免這一問題的呢?**

Tony:在我看來,CORBA問題就是指“為所有人設計”。如果你希望通過某個規(guī)范解決每個人的問題,那你肯定無法得到一個成功的規(guī)范。這就像設計界中的人所說的一樣,“如果你將所有美麗的顏色混合在一起,只會得到一個骯臟的顏色”。這一點對于軟件設計來說也一樣,當你在設計例如Swagger這樣的產品時,對于它的功能,必須以一種干凈的、清晰的方式進行設計。當設計走上正軌時,就有許多的改進空間,但一切前提在于要把握好方向。

Mike**:SmartBear在Swagger的發(fā)展中扮演了怎樣的角色,為什么他們會在這個節(jié)骨眼上[選擇](http://developers-blog.helloreverb.com/swagger-smartbear/)帶領Swagger**今后的發(fā)展?

Tony:SmartBear是最早一批將Swagger整合到他們的工具中的軟件商之一。我們已經合作了很長一段時間,在API這一領域中,他們最適合領導Swagger的發(fā)展。他們將通過正確的途徑打造開放的規(guī)范、工具以及社區(qū)。他們很清楚地看到,即使對于以Swagger為基礎打造的商業(yè)產品來說,整個業(yè)界也能夠得益于一個一致的API模型。SmartBear在API測試領域已經浸淫多年,他們在API設計方面的聲望很可能已超越了其它的公司。

Mike**:如今SmartBear即將接管Swagger的發(fā)展,那么你在這一規(guī)范的未來發(fā)展中又將扮演什么樣的角色?**

Tony:我當然也在計劃繼續(xù)為這一項目做出自己的貢獻。對于需要這一規(guī)范的人來說,我們將推出更多的資源與更好的支持,我也將繼續(xù)工具鏈與規(guī)范方面的工作。

Mike**:Leonard Richardson**將標準的發(fā)展描述為一種連續(xù)的發(fā)展,從法令到個人、從個人到企業(yè)、再從企業(yè)到開放。第一階段的法令就是得到共識的行為,而最后階段則是標準委員會的工作成果,例如W3C**、IETF、OASIS等等。按照Leonard的評估來看,Swagger創(chuàng)立時還是一種應用于你的公司的個人標準,然后很快成為了一個企業(yè)標準,得到了大量的組織的使用。在你看來,Swagger**能否在短期內成為一個開放標準呢?

Tony:我們正在為Swagger規(guī)范創(chuàng)建正確的治理結構,這個過程將是公開的,問題只在于這個結構需要有多正式。我預計當分析過程結束后,就應當能夠得到正確的結論了。

Mike**:還有沒有什么我還沒有問及的問題,是你打算與讀者分享的?**

Tony:我想你的問題已經基本涵蓋了所有的部分,感謝你的寶貴時間。

關于受訪者


Tony Tam是NDN的新興技術部門的副總裁,同時也是工程部門的執(zhí)行副總裁,負責協(xié)助全公司的技術問題。在加入NDN之前,Tony曾是Reverb的創(chuàng)始人與CEO,他在當時領導著網站的創(chuàng)新詞匯導航系統(tǒng)的開發(fā)工作。他是MongoDB Masters小組成員之一,并且領導著Swagger API框架的開源工作。在加入Reverb之前,他曾是Think Passenger的創(chuàng)始人,兼任工程部門的高級副總裁,這是一家設計客戶協(xié)作軟件的供應商。在那之前,他曾在Composite Software擔任工程師主管,幫助公司開發(fā)了第一代與第二代查詢處理引擎,并領導著具有專利權的,基于成本的聯(lián)合查詢優(yōu)化器這一產品的研究與實現(xiàn)。他也曾在Galileo Labs的生物信息小組領導軟件開發(fā)工作,這是一個基于硅谷的新藥研發(fā)公司。

查看英文原文:APIs with Swagger : An Interview with Reverb’s Tony Tam

以上內容是否對您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號