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

Question

我需要我的Node REST API进行版本控制。我正在使用swagger 2.0作为验证中间件和文档。目前，我只有一个用于所有目的的swagger yml文件。

我使用url前缀（版本号：/v1/../v2/…等）来支持节点Rest API中的版本控制。我需要在任何时候支持多个版本。

1. 我应该为每个API版本创建一个单独的swagger yml文件吗？如果是，如何在 swagger 验证中间件中加载/管理多个 swagger yml 文件
2. Swagger 2.0 格式规范是否允许在同一文件中定义版本化路径。

Answer 1

Swagger没有指定版本化方案，仅仅是因为没有单一的解决方案，并且强迫一种方法使用该规范是没有意义的。以下是我见过的常用技巧:

1）将您的身份验证绑定到一个版本。我认为这是处理版本控制的最酷的方法，但也是支持和维护成本最高的方法。例如，基于用于访问服务的 API 密钥，您可以跟踪他们希望访问的版本，并将其路由到正确的服务器。在这种情况下，您可以简单地运行具有不同 swagger 定义的多个服务。

2）使用路径部分来指示版本。这意味着您的路径中有一个/v2或/v3，在此基础上，一些路由逻辑将您指向正确的服务器。同样，一个单独的昂首阔步定义。

3）根据某些标头，让用户选择要与哪个服务器交谈。这很不直观，但它可以工作。您应该始终有一个默认版本（通常是最新版本）

也就是说，上述所有解决方案都意味着多个swagger文件。您可以使用$ref语法来链接和重用部分规范。

我相信使用swagger工具，您可以有多个实例监听请求。您只需要在它们前面有一个路由层来处理您选择的不同版本。