swagger - OAS3 指定的服务版本控制

Question

我们目前正在使用 OpenAPI 服务规范 v3 OAS3 指定一个新的 REST 服务 API。 .由于一系列不同的原因，我们需要/希望从一开始就对服务 API 进行版本控制(这是由我们无法控制的因素强制执行的)。
我们想要使用的版本控制方案是 URL 路径版本控制 - 即类似 .../v1/ourservice 的东西.
有人知道如何在 OAS3 规范中跟踪这样的版本控制方案吗？
到目前为止我只看到了一个全局version OAS3 中的属性 - 但没有任何东西可以让我们轻松地在一个 YAML 文件中指定多个版本(或者这首先是错误的方法吗？)。
仅供引用，我们计划使用自顶向下的方法，即将我们的服务 API 定义为 OAS3 YAML，然后使用 Swagger 生成器继续生成服务器和/客户端代码。

Answer 1

version在 OpenAPI 文档中是指文档的版本而不是 API 的版本。

来自 the spec :

version string REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

因此，不幸的是，您需要关注三个版本。这是它们的样子:

规范版本(必须是在 https://github.com/OAI/OpenAPI-Specification 中定义的版本之一)
示例:

oepnapi: 3.0.2

文档版本。我通常将其公开为自动生成的文档的 git SHA1 哈希。
示例(见 version):

  title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: support@example.com
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

API 版本。
有些人认为路径版本控制有争议，但我们中的许多人(包括我自己)由于许多我们无法控制的不同原因不得不这样做。在所有规范版本中实现这一点的常用方法是在 baseUrl 中定义路径版本。 .例如，您的基本 URL 可能是 /nested/v1或者干脆 /v1 .不幸的是，这只会涵盖 v1方法。

OAS3 支持 server variable templating用于更复杂的 API 版本配置。这看起来正是你要找的。但是，OpenAPI Generator 中的所有生成器尚未完全支持这些变量。如果您有特定的生成器，请 open an issue对于这些最初的支持似乎只存在于 Ruby、PHP、python 和 JavaScript ES6 客户端生成器中。