node.js - 使用 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-validation 中间件中加载/管理多个 swagger yml 文件
2. Swagger 2.0 格式规范是否允许在同一文件中定义版本化路径。

Answer 1

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

1) 将您的身份验证与版本相关联。我认为这是处理版本控制的最酷方式，但也是支持和维护成本最高的方式。例如，基于用于访问您的服务的 api key ，您可以跟踪他们期望访问的版本，并将其路由到正确的服务器。在这种情况下，您可以简单地运行多个服务，使用不同的 swagger 定义。

2) 使用路径部分来指示版本。这意味着您的路径中有一个 /v2 或 /v3，并且基于此，一些路由逻辑将您指向正确的服务器。再次，一个单独的 Swagger 定义。

3) 基于一些 header ，让用户选择要与哪个服务器通信。这是非常不直观的，但它可以工作。您应该始终拥有一个默认版本(通常是最新版本)

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

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