OpenAPI 中的服务版本控制

Question

我们即将为我的客户端实现一个服务 API，它由许多服务组成，比如说 ServiceA、ServiceB 和 ServiceC。每个服务都可以随着时间的推移（独立地）引入新版本，而旧版本仍然存在。所以我们可能有：

我们需要使用 OpenAPI 记录此 API。我对 OpenAPI 不太熟悉，但据我所知，您通常对整个 API 进行版本控制，而不是单独的服务。

通常如何使用 OpenAPI 记录此类版本控制？我个人认为有两种选择，但我很可能遗漏了一些东西：

在文档中将相同服务的每个版本添加为单独的服务（但随着时间的推移，这会导致 API 臃肿，其中包含大量服务）
每次单个服务更改版本时，增加所有服务版本和整个 API 的版本，因此每个服务总是有版本 1、2 和 3，即使其中一些是相同的（但这会引入很多不必要的服务版本）。

任何输入将不胜感激。

Answer 1

也许有点晚了，但请考虑一下这个观点。

如果服务API是由紧凑组件实现的，那么API也应该是紧凑的。您的服务的使用者对您的版本控制策略并不感兴趣，而只是对向后兼容性违规和/或新功能添加的扩展感兴趣。

要求消费者知道各个服务的所有版本号绝对超出了范围。他不想知道这一点，他想要一个完整的、紧凑的包裹。

如果您的服务没有什么共同点，那么您最好的解决方案可能是具有定制版本的单独 OpenAPI 文档。关键是 - 您不会阻止依赖于剩余服务的无关客户/消费者开发您的组件，并且您不会因为客户感兴趣的领域而进行零更改版本更改来打扰客户。

另一方面，您也可以保留与端点分开的版本号。

像这样的事情：

openapi: 3.1.0
info:
  version: 2.0
  servers:
  - url: http://somewhere.com/v2
paths:
  /some-action:
    ...

代替

openapi: 3.1.0
info:
  version: 2.0
  servers:
  - url: http://somewhere.com
paths:
  /v2/some-action:
    ...

现在，您的客户需要配置您的服务地址http://somewhere.com/v2并将其用于所有服务 A、B、C。一旦您决定发布新的主要版本 /v3，该版本会破坏服务 A 的兼容性，并为 B 带来新功能、C，可能还有新的 D：

您可以为现有客户保留http://somewhere.com/v2使用旧服务组件版本运行。
API 可能会以某种方式通知他们有关使用已弃用的端点的信息
您可以将这两个 API 规范保留在您的开发文档工具中。
仅使用 A、B 的客户可能只是在资源 URI 级别上将http://somewhere.com/v2交换为http://somewhere.com/v3，而不更改/重建任何代码。
使用 A 的客户可能会继续使用旧版本，并通过仅解决与 A 一起工作的代码来设计向 /v3 的缓慢转变
新客户可以从使用具有紧凑 API 的当前LIVE版本开始。您绝对不想强迫他们分别了解每个服务的当前最新版本，他们server也希望将版本控制封装在其中。此外，他们可以免费使用 D。