所以您著手建構一個很棒的 API...太棒了！或者您已經有一個 API...那就更好了！
為您的 API 建立定義是 API 開發中經常被忽略的重要步驟。API 定義 (有時稱為 API 規格或描述格式) 旨在提供一種機器可讀的 API 描述格式。它們與語言無關，因此無論您選擇哪種語言，都可以從中受益。
目前，最常用的 API 定義是 OpenAPI 規格。OpenAPI 規格 (OAS) 以原始 Swagger 規格為基礎，定義了 API 的 RESTful 標準。OAS 定義對應 API 的資源和操作。
本文說明了建立定義的一些好處，以及一些可以讓您更輕鬆的工具。
為何建立定義
您的 API 定義可以用於
- 協助內部人員了解 API 並就其屬性達成共識：這對我的上一家公司很有幫助。API 定義允許 Swagger UI 等文件工具將 API 可視化。我們使用 Swagger UI 將我們所有內部 API 可視化，以便開發人員可以快速輕鬆地使用上游和下游服務。SwaggerHub 具有團隊和企業級功能，可設計、檢視和協作處理 API。
- 協助外部人員了解 API 及其功能：同樣，Swagger UI 是一個廣泛使用的文件視覺化工具，我個人最喜歡的是 Marvel API。還有其他很棒的文件解決方案，它們將 API 定義檔案作為輸入，例如 ReDoc、ReadMe 和 Slate。
- 為您的 API 建立測試：您的 OAS 定義提供了一份合約，描述當有人呼叫您的 API 時，回應會是什麼樣子。此合約可以重新用於建立測試案例。這可以大幅減少團隊測試 API 所需的設定量。您可以使用 ReadyAPI 從您的 API 定義建立功能測試、負載測試、執行安全性掃描和虛擬化您的 API，您可以透過 匯入您的 API 定義來啟動所有這些。
- 產生實作程式碼和 SDK：除了產生文件外，OpenAPI 定義還可用於透過建立實作程式碼和 SDK 來加速開發。API 定義檔案可以匯入許多不同的工具，例如 Swagger Codegen 和 SwaggerHub。它們可以用許多不同的語言建立程式碼，例如 Java、Scala 和 Ruby。建立實作程式碼，這樣您就不必從頭開始編寫 API 程式碼。
- 讓您的 API 上線：API 閘道，例如 Amazon API Gateway、Azure、Apigee 或 Google Cloud，全部都採用 API 定義來建立即時 API。
- 監控您的 API：理想情況下，您希望在您的客戶注意到之前，就知道您的 API 是否有問題。如果您將您的定義匯入 Alertsite 等工具，則可以自動監控 API。
您的 API 定義應該作為您 API 的真實來源。它可以用於實作 API、記錄 API，以及為確保您的 API 成功所需的工具提供支援。
建立 API 定義
現在我已經說明了您可能建立定義的原因，接下來我將說明一些方法。您有幾個選項
- 先設計您的 API，並選擇性地從定義建立實作程式碼
- 呼叫您的 API，並使用這些請求來建立定義
- 讓您的程式碼產生定義
1. 先寫定義 (然後實作)
「設計優先」方法主張在編寫任何程式碼之前，先編寫 API 定義。這是一種相對較新的方法，但正迅速流行起來。在編寫任何程式碼之前發現設計問題，比在實作完成後才發現問題更有效率。
像 SwaggerHub 這樣的團隊工具提供了許多功能，可讓您設計 API 並協同作業。您可以設定管理員等級的權限、讓使用者能夠對定義進行變更並合併變更，而且您會得到一個視覺化編輯器。您也可以研讀如何建立符合 OpenAPI 的定義，並使用文字編輯器來建立 YAML 檔案。如果您想要其他工具，而且不想使用 SwaggerHub，則可以使用 Swagger-Editor 來編輯、Swagger-UI 來記錄，以及 Swagger-Validator 來驗證您的定義。
建立定義後，您可以為您的 API 建立實作程式碼。SwaggerHub 讓您能夠輕鬆地建立實作程式碼 (伺服器存根)。您也可以使用這個 開放原始碼程式庫 Swagger-Core 來執行相同的作業。您需要新增任何無法單獨由定義描述的業務邏輯。您可以設定流程，以便在您的 API 定義變更時建立實作程式碼。
2. 使用 Swagger Inspector 從 API 呼叫建立定義
如果您已經實作了您的 API (至少部分實作)，您可以直接從 Swagger Inspector 對您的 API 發出請求。
Swagger Inspector 可以執行 API 請求、驗證回應並建立 OpenAPI 定義。您可以透過呼叫端點、選取端點，然後按一下 [建立 API 定義] 來建立現有 API 的文件。
這會自動產生您選取之端點的 OpenAPI 檔案，節省寶貴的開發時間。我們將定義免費儲存在 SwaggerHub 中，您可以立即存取 API 的文件。您也可以匯出檔案並建立用戶端 SDK。
這種方法會產生 API 的快照，但如果您的 API 沒有太多變更，那就沒有關係！這可能是建立 API 定義最快的方法，也是我最喜歡的方法，因為它使用我們的新產品 Swagger Inspector。如果您有任何建議，請務必在右下角的 Widget 中留下意見反應！
3. 程式碼產生的定義
有幾個專案可以協助您從程式碼產生 API 定義。在 SmartBear，我們花費最多時間的專案是 Swagger-Core，它可以用於 Java 7 或 8 以及 maven 3.0.4+。SmartBear 也貢獻於 Scala 和 Javascript 專案，這些專案會根據您的程式碼建立定義。如果您使用不同的語言，很有可能只要稍微搜尋一下就能找到相關的函式庫。例如，SwashBuckle 是一個 .NET 函式庫，可以做到相同的事情。
從程式碼建立定義是一種絕佳的方式。它可以確保您的定義與您的實作一致。但這也帶來一些挑戰。例如，您需要確保定義具有易於理解的描述和範例。如果您有專職的技術寫手，他們應該與您的開發人員密切合作，才能讓這種方法順利運作。
無論您選擇使用哪種方式，我們都希望這些提示能幫助您建立出色的 API！