OpenAPI 規格，先前稱為 Swagger，描述 API 的各個層面。 OpenAPI 規格（規格）描述 API 的端點、參數和回應。 OpenAPI 規格是以 YAML 或 JSON 撰寫，並由工具用來產生檔、測試案例和客戶端連結庫。 透過具有 OpenAPI 規格，API 產生器可以確保其 API 能正確描述、更容易存取且更容易跨各種應用程式和服務進行整合。
以下是您應該考慮為 API 使用 OpenAPI 規格的原因：
- 以標準化的方式記錄 API。 以一致且人類可讀取的格式記載 API 規格。
- 產生用戶端 SDK。 使用 Kiota 之類的工具，以各種程式設計語言自動產生用戶端連結庫。
- 建立模擬 API。 根據 API 規格建立模擬伺服器，這可協助您在尚未實作實際 API 的早期開發階段。
- 改善共同作業。 提供不同的小組（前端、後端、QA），並清楚瞭解 API 的功能和限制，這有助於新小組成員快速趕上。
- 簡化測試和驗證。 針對規格自動驗證 API 要求和回應，這可讓您更輕鬆地識別差異。
- 與 API 管理工具整合。 使用許多 API 管理工具和閘道輕鬆整合、部署及監視 API，例如 Azure API 中心和 Azure API管理。
- 簡化 API 閘道設定。 使用 OpenAPI 規格來設定 API 閘道，並將路由、轉換和跨原始來源資源分享設定等工作自動化。
藉由使用 OpenAPI 規格，您可以建立設計良好且一致記載的 API。 在內部和外部取用者中，它們也更容易維護且更容易使用。
還沒有 OpenAPI 規範嗎？
為已經存在的 API 手動撰寫規格需要時間，且會偏離 API 的真正功能。 另一個方法是記錄 API 回傳的內容，然後從中產生規格。
| Approach | 你會得到什麼 | 需注意的事項 |
|---|---|---|
| 手寫 | 可完全掌控描述與範例 | 這需要時間，而且會偏離真正的 API |
| 從程式碼註解產生 | 一個能與程式碼同步的規範 | 你需要存取 API 的程式碼，而框架必須支援它 |
| 從錄製的流量資料產生 | 這是針對任何你可以呼叫的 API 的規範，包括你不擁有的 API | 它只涵蓋你記錄的請求，所以請測試你需要的 API 部分 |
Dev Proxy 會記錄你的應用程式與 API 之間的請求與回應，並從中產生 OpenAPI 規範。 關於步驟，請參見 「產生 OpenAPI 規範」。
