Swagger 框架有助於為 API 定義與語言無關、人類可讀的格式，簡化實作、推動採用並穩定開發。
為 API 產生 Swagger 規格一般有兩個流程
- 執行階段 Swagger 產生：在此方法中，Swagger 合約是根據針對各種資源、方法和控制器新增的中繼資料從 API 產生。此中繼資料將在執行階段產生 Swagger 合約、用戶端程式碼和其他成品。通常，此中繼資料將以程式碼註解的形式存在。當針對其資源呼叫各種方法和函數時，工具會觸發，並從 API 中定義的中繼資料產生 Swagger 合約。
- 建置階段 Swagger 產生：在此方法中，Swagger 合約是在預先處理 API 時（即在執行階段之前）產生。API 內各種資源、方法和函數的註解有助於產生 Swagger 規格。這些註解通常採用預定義的特殊語法，具體取決於您用於產生合約的工具類型。該工具會掃描您的 API 程式碼以尋找這些特殊註解，並產生 Swagger 合約作為輸出。
這兩種方法都有其優缺點。在執行階段產生 Swagger 規格會從程式碼產生更精確的 API 合約，但會以額外相依性形式的軟體負載、開發時間為代價，並且可能會增加系統的一些額外負荷。相反地，在 API 執行階段之前產生 Swagger 合約是一個更輕量的過程，但產生的 Swagger 合約很可能無法準確描述您的 API，因為必須手動維護。
SwaggerHub 團隊最近發佈了一份免費資源 — 使用 Swagger 為現有 API 建立文件 — 研究產生 API 的 Swagger 的這兩種方法。
您將學習
- API 文件的重要性
- 為什麼要使用 Swagger 建立文件
- 將 Swagger 新增至 API 的方法
- 為您的 Swagger 規格建立文件
取得您的副本！