使用Swagger 2.0進行REST API版本控制

Question

我需要對我的Node REST API進行版本控制。 我使用swagger 2.0作為驗證中間件和文檔。 目前我只有一個swagger yml文件，用於所有目的。

我正在使用url前綴（版本號：/ v1 / ... / v2 / ...等）來支持我的Node Rest API中的版本控制。 我需要在任何時候支持多個版本。

1. 我應該為每個API版本創建一個單獨的swagger yml文件嗎？ 如果是，如何在swagger驗證中間件中加載/管理多個swagger yml文件
2. Swagger 2.0格式規范是否允許在同一文件中定義版本化路徑。

Answer 1

Swagger沒有簡單地指定版本控制方案，因為沒有單一的解決方案，強制一種方法使用規范是沒有意義的。 以下是我見過的常用技巧：

1）將您的身份驗證綁定到版本。 我認為這是處理版本控制的最酷方式，但也是支持和維護最昂貴的方法。 例如，基於用於訪問服務的api密鑰，您可以跟蹤他們期望訪問的版本，並將其路由到正確的服務器。 在這種情況下，您可以簡單地運行多個服務，並使用不同的swagger定義。

2）使用路徑部分指示版本。 這意味着您的路徑中有/v2或/v3 ，並且基於此，某些路由邏輯將您指向正確的服務器。 再一次，一個單獨的招搖定義。

3）基於某些標題，讓用戶選擇要與之通話的服務器。 這非常不直觀，但它可以工作。 你應該總是有一個默認版本（通常是最新版本）

也就是說，上述所有解決方案都意味着多個招搖文件。 您可以使用$ ref語法來鏈接和重用規范的各個部分。

我相信使用swagger工具，您可以讓多個實例監聽請求。 您只需要在它們前面有一個路由層來處理您選擇的不同版本。