openapi - OpenAPI 中的服务版本控制

Question

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

ServiceA v1

服务A v2

ServiceB v1

ServiceC v1

服务C v2

服务C v3

我们需要使用 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 可能会通知他们 in some way关于使用已弃用的端点

您可以将这两个 API 规范发布在您的开发文档工具中。

只使用A、B的客户可以互换http://somewhere.com/v2为 http://somewhere.com/v3在资源 URI 级别上，而不更改/重建任何代码。

使用 A 的客户可能会继续使用旧版本，并通过地址 设计向/v3 的缓慢转移。仅 与 A 一起使用的代码

新客户可以使用当前的 LIVE 开始版本，具有紧凑的 API。您绝对不想强制他们分别了解每个服务的当前最新版本，他们想将版本控制封装在 server 中。以及。此外，他们可以免费使用 D。