什麼是 OpenAPI？

OpenAPI 規格（以前稱為 Swagger 規格）是 REST API 的 API 描述格式。OpenAPI 檔案可讓您描述整個 API，包括

• 可用端點 (/users) 和每個端點的操作 (GET /users、POST /users)
• 每個操作的操作參數輸入和輸出
• 驗證方法
• 聯絡資訊、授權、使用條款和其他資訊。

API 規格可以使用 YAML 或 JSON 編寫。該格式容易學習，並且對人類和機器都可讀。完整的 OpenAPI 規格可以在 GitHub 上找到：OpenAPI 3.0 規格

什麼是 Swagger？

Swagger 是一組圍繞 OpenAPI 規格建構的開源工具，可協助您設計、建構、撰寫文件和使用 REST API。主要的 Swagger 工具包括

• Swagger Editor – 基於瀏覽器的編輯器，您可以在其中編寫 OpenAPI 定義。
• Swagger UI – 將 OpenAPI 定義呈現為互動式文件。
• Swagger Codegen – 從 OpenAPI 定義產生伺服器存根和用戶端程式庫。
• Swagger Editor Next (beta) – 基於瀏覽器的編輯器，您可以在其中編寫和檢閱 OpenAPI 和 AsyncAPI 定義。
• Swagger Core – 用於建立、使用和處理 OpenAPI 定義的 Java 相關程式庫。
• Swagger Parser – 用於剖析 OpenAPI 定義的獨立程式庫。
• Swagger APIDom – 為描述各種描述語言和序列化格式的 API 提供單一、統一的結構。

為何使用 OpenAPI？

API 描述自身結構的能力是 OpenAPI 中所有卓越功能的根源。編寫完成後，OpenAPI 規格和 Swagger 工具可以透過各種方式進一步推動您的 API 開發

• 設計優先使用者：使用 Swagger Codegen 為您的 API 產生伺服器存根。剩下的唯一事情是實作伺服器邏輯 – 您的 API 就可以上線了！
• 使用 Swagger Codegen 以 40 多種語言為您的 API 產生用戶端程式庫。
• 使用 Swagger UI 產生互動式 API 文件，讓您的使用者可以直接在瀏覽器中試用 API 呼叫。
• 使用規格將 API 相關工具連接到您的 API。例如，將規格匯入 SoapUI 以為您的 API 建立自動化測試。
• 還有更多！查看與 Swagger 整合的開源和商業工具。