談到 API 設計和 Swagger (OpenAPI) 規格，很少有人能像 Arnaud Lauret 一樣充滿熱情，他以 API 大師 (@apihandyman) 的稱號廣為人知。Arnaud 在 IT 銀行業工作了近 13 年，擔任過程式設計師和專案經理。現在，他在 AXA Banque 擔任 IT 架構師，負責 API 專案和管理。
9 月，Arnaud 發布了 API 風格手冊，旨在透過快速且輕鬆地存取選定和分類的資源，協助 API 設計師解決 API 設計挑戰並建立 API 設計指南。Arnaud 也是撰寫 OpenAPI 規格的 10 部分 Swagger 教學課程的創作者。他的教學課程對於任何剛開始使用 Swagger 開源工具或 SwaggerHub 的人來說都是寶貴的資源。
本月稍早，我們很榮幸能邀請 Arnaud 參與我們的 API 專家小組：為 2017 年開發 API 策略，地點在 SmartBear 總部。在小組會議之前，我們與 Arnaud 坐下來，進一步了解他開始使用 Swagger 的經驗，以及良好 API 設計的常見特徵。
您能否談談您開始使用 Swagger 的經驗？
幾年前，我們開始了一個 API 專案，並且希望為我們的 API 提供文件，因此我們開始使用 Swagger 註解從程式碼產生文件。當時我還不知道這種註解背後有一種格式 — OpenAPI 規格。最初的結果並不是很理想，因為我們沒有給予撰寫註解的開發人員足夠的指示，因此結果作為文件並不是真的可用。
就在那時，Swagger 2.0 推出了 — 採用新的規格、編輯器以及 YAML。我們需要更新我們的文件，這非常複雜，因為文件是在程式碼中。所以我開始玩這種格式，方法是擷取現有的產生文件並將其轉換為 Swagger 2.0，我發現它非常容易解析和操作。
我建立了另一個模組，修正了文件中存在的許多問題。這觸發了我想要廣泛使用此格式的渴望。當時我感覺到我們可以利用它做很多很多的事情。我們首先使用 OpenAPI 規格格式撰寫規格。我們計劃在設計期間編寫一些控制項，方法是解析規格來查看新設計的 API 是否符合我們的指南 — 新文件是否完整、是否到處都有描述......
這是逐步發生的，每天都會發現新事物。最後，我在我的部落格上撰寫了 10 部分的教學課程。關於規格的最重要一點是它非常簡單，而且您不需要任何複雜的東西來解析它並用它來做事。
您在 REST API 中看到哪些常見的設計特徵/指南？
所有指南都真正專注於 — 好的，我們想要執行 REST API — 什麼是 REST API？我們有資源，我們必須使用 HTTP 協議、正確的 HTTP 狀態等等。它們以不同的方式講述故事，但它們都從非常技術的角度以相同的方式解釋同一件事。當您問這個問題時，它讓我震驚，它們沒有談論真正的問題 — 如何查看 API 是否提供功能。而不僅僅是透過 HTTP 協議提供資源。我們必須要有這些類型的文件，因為我們需要從技術角度將框架圍繞在 API 設計周圍。
但我也認為所有需要設計 API 的公司都需要從功能角度設計 API 的功能指南。有一些書籍談論到這一點，但所有這些指南實際上都具有技術性。
有興趣了解更多嗎？
隨時關注 Arnaud 的最新 APIHandyman 部落格資源。剛開始使用 OpenAPI 規格嗎？請在此處查看我們的 OpenAPI 資源區段。