在本系列的部落格文章中，我們將協助您深入了解 Swagger，了解它的用途以及如何使用它將您的 API 提升到新的水平。每篇文章將涵蓋這些方面之一。
讓我們來談談問題：我們有一個想要記錄的 API。具體來說，是一個 REST API（我們稍後將會深入探討「REST」的含義）。
我們可以維護一份包含該資訊的文件或 HTML 網站，甚至讓某些工具從我們的程式碼中產生。這種方法的缺點是我們需要手動（或透過半自動流程）維護它，而且雖然它是人類可讀的，但它並非真正的機器可讀。
另一種方法是使用 WADL，它可以由某些工具產生。在這種情況下，它是機器可讀的，但絕對不是人類可讀的。此外，手動編寫 WADL 是一個繁瑣的過程。
為了尋求更簡單的解決方案，Swagger 應運而生。Swagger 是一組規則（換句話說，是一種規格），用於描述 REST API 的格式。該格式既是機器可讀的，也是人類可讀的。因此，它可以被用於產品經理、測試人員和開發人員之間共享文件，也可以被各種工具用於自動化 API 相關流程。
當我們說 REST 時，我們不一定會遵循 RESTful 規則。我們指的是 REST API 背後的基本概念。雖然 WADL 幾乎涵蓋了任何可能的 API 設計，但以複雜性為代價，Swagger 的目標是涵蓋更常見的設計模式，同時更容易編寫和使用。
在我們最新的版本中，Swagger 2.0，我們已經使該格式可以接受 JSON 和 YAML 兩種格式，使其更容易編輯。
為了幫助您了解 Swagger 的樣子，請查看以下範例
swagger: "2.0"
資訊
版本: "1.0"
標題: "Hello World API"
路徑
/hello/{user}
get
描述: 向使用者返回問候語！
參數
- 名稱: user
所在位置: path
類型: string
必要: true
描述: 要問候的使用者名稱。
回應
200
描述: 返回問候語。
結構描述
類型: string
400:
描述: 提供了「使用者」中的無效字元。
在上面的範例中，我們描述了一個簡單的「Hello World API」。它公開了一個 URL -「/hello/{user}」。「user」是 API 的單一參數，定義為路徑的一部分，我們說它是字串。我們還描述了成功的響應，並提到它也是字串。如果「user」包含無效字元，則可能會收到一般 400 錯誤。您還可以發現在整個操作過程中，我們提供了額外的文件。
差不多就是這樣了 - 這就是 Swagger 的簡要概述。Swagger 規格可供所有人閱讀，網址為 https://swagger.dev.org.tw/specification 或閱讀此 Swagger 教學。它包括有關如何定義路徑、參數、回應、模型、安全性和更多資訊。Swagger 規格本身是開放原始碼的，並在 ASL 2.0 下提供。
在接下來的部落格文章中，我們將介紹如何開始在您的專案中使用 Swagger、它如何融入一般的 API 生命周期，以及有哪些可用的工具，包括開源和商業工具。
如果在本系列中，您希望看到我們涵蓋有關開始使用 Swagger 的任何特定方面，請隨時與我們聯繫並提出要求 - 我們將盡力提供相關資訊。