作者：Jeff Cousens，Civis - Analytics 的資深工程師
不久之前，我們決定 Civis 平台中的所有新功能都將實作為 API 端點和前端程式碼的組合。同時，我們決定所有端點都將提供給我們的客戶使用。也就是說，如果您可以透過 Civis UI 使用某項功能，您也可以利用底層 API 進行程式化存取。這已經成為一個巨大的力量倍增器，正如您在 Civis API：擴展您的資料科學 中所讀到的那樣。這也表示我們的工程團隊不能因為符合 UI 的需求就破壞我們的 API 合約。
一個解決方案是依賴 API 版本，這是從一開始就內建在 Civis API 中的。但即使有了版本，我們仍然需要知道變更是否構成重大變更。我們認為以下情況屬於重大變更：
- 移除端點
- 新增新的必要請求參數
- 移除或變更請求參數或回應屬性的類型
發布的指南是好的，但它們可能會出錯。我們偏好利用自動化解決方案來編纂我們的最佳實務，並明確制定和強制執行我們的政策。有了這個想法，我們編寫了 Swagger::Diff。Swagger::Diff 會比較兩個 Swagger 規格，並識別任何重大變更。例如，若要將 Swagger Project 的擴充寵物商店範例與最小寵物商店範例進行比較，並驗證擴充範例與最小範例是否向後相容：
$ gem install swagger-diff
$ wget https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-minimal.json
$ wget https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json
$ swagger-diff petstore-minimal.json petstore-expanded.json
交換引數的順序，它會比較最小範例與擴充範例，並標記最小範例中遺失的端點、參數和屬性。
$ swagger-diff petstore-expanded.json petstore-minimal.json
- 遺失的端點
- delete /pets/{}
- get /pets/{}
- post /pets
- 不相容的請求參數
- get /pets
- 遺失的請求參數：tags (type: array)
- 遺失的請求參數：limit (type: integer)
- 不相容的回應屬性
- get /pets
- 遺失預設回應
Swagger::Diff 也直接與我們的測試套件整合。人們可能會忘記執行檢查，但持續整合 (CI) 不會。加上一個會傳回我們目前 Swagger 規格的 API 端點，它讓我們可以透過 請求規格 簡單輕鬆地比較 API 的兩個版本。
it 'is backwards compatible' do
production_swagger = open('https://host.domain/endpoints').read
get '/endpoints'
test_swagger = response.body
expect(test_swagger).to be_compatible_with(production_swagger)
end
每次我們推送程式碼時，我們的 CI 都會針對生產規格測試開發分支，如果引入了任何向後不相容的變更，則會失敗並顯示詳細說明變更的訊息。這保證了不會有任何向後不相容的變更意外地進入我們的 API。
我們已在 BSD 3-Clause 授權下開源 Swagger::Diff，將 gem 發布到 RubyGems.org，並將原始碼發布到 GitHub。我們鼓勵您將其加入您的 CLI 工具組、專案的 CI 或測試套件，並歡迎您提出問題或提取請求。