Swagger ，讓大家的 API 與世界接軌

最近有個專案要建立 API 文件，使用了 Swagger 這款服務，發現 Swagger 除了是 OpenAPI 規範的領航者，它的故事也展現了企業對開放精神 的風範。

 

 

OpenAPI 這個計劃由 Linux 基金會主持，是為了建立世界各地共通的 API 規範。另外有一家 Reverb technologies 公司，開發了一款名叫 Swagger 的 API 規範，整合了包含 Paypal 在內超過 500 家企業開發的 API，Swagger 在 2015 年度被貢獻給 OpenAPI 成為標準規範，後續也把維護、宣傳 Swagger 的工作交給 SmartBear 公司， SmartBear 不僅繼續維護這個開源專案，也建立了以協助組織靠 Swagger 開發 API 的服務 SwaggerHub。

 

一開始我心想 Reverb technologies 這家公司為什麼要把自己的產品開放出來，難道是為了商業考量嗎？因為一旦被當成公開規範，就會有更多人需要他們協助開發這個 API 服務。但即便如此，受益最大的仍然是整個使用 API 規範的社群，有了統一的規範可以依循，開發的門檻就更低，又方便跟其他別人開發的服務整合，一旦更多公司進來做像是 SmartBear 的這種協助開發 API 的服務，廠商就有更多選擇。衍生的服務例如建立說明文件、整合測試.....等也會更方便，當服務變得多樣，互相學習也有助於整個技術的發展。

 

 

 swagger.io 主要是讓你方便建立符合 OpenAPI 規範的說明文件，十分容易使用，大概唯一的門檻就只是撰寫一個可以套用的 JSON 或是 YAML 資料集即可。

 

 

需要 Swagger 範例的話，可以到 Swagger 的範例頁面就有完整的呈現。可以看到上面有一個網址框，後面接 Explorer 按鈕。其實這頁面只是 Swagger 讀了一個 API 規範的 JSON 產生的。你需要的就是產生一個符合 OpenAPI 規範的 JSON 填進去，由於只要撰寫 JSON，在範例頁面又可以方便檢測是否有錯誤，這使得產生 API 說明頁面變得容易許多。

 

 

為了寫這篇，在查資料的過程中，不經意也找到政府資料集的 API 說明文件，運作跟 Swagger 介面也很像，可以看到它也是讀了符合 OpenAPI 規範的 YAML 所產生的。今年三月唐鳳政委曾舉辦一個「共通性應用程式介面開放規範研議」，其中投影片文件檔案就有針對 OpenAPI 規範做說明，不過有趣的是，從會議的逐字稿中發現，對於 Swagger.io 這種使用讓機器看的格式撰寫，唐鳳他比較喜歡像 API Blueprint 這種用 Markdown 的格式書寫，因為在插入範例、附圖等一些多媒體的內文格式有較大的彈性，是跟寫 YAML、JSON 等機器的語言時完全不一樣的感覺。

 

 

 

我想無論是哪種方式，在做出好的文件、設計好的 API，主體都是閱讀、使用的人，對於還沒有經驗的開發者來說，好的規範是更有助於達成理想。在導入 Swagger.io 後，相信政府的開放資料集今後也會愈來愈朝這套規範運作，樂見各種 API 的介接也會愈來愈容易。