OAS3 指定的服务版本控制

Question

我们目前正在使用 OpenAPI 服务规范 v3 OAS3指定一个新的 REST 服务 API 。由于一系列不同的原因，我们需要/希望从一开始就对服务 API 进行版本控制（这是由我们无法控制的因素强制执行的）。

我们想要使用的版本控制方案是URL 路径版本控制——即类似于.../v1/ourservice.

有人知道如何在 OAS3 规范中跟踪这样的版本控制方案吗？

到目前为止，我只version在 OAS3 中看到了一个全局属性 - 但没有任何东西可以让我们轻松地在一个 YAML 文件中指定多个版本（或者这首先是错误的方法吗？）。

仅供参考，我们计划使用自顶向下的方法，即将我们的服务 API 定义为 OAS3 YAML，然后使用 Swagger 生成器继续生成服务器和/客户端代码。

Answer 1

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

从规范：

版本 字符串 REQUIRED。OpenAPI 文档的版本（不同于 OpenAPI 规范版本或 API 实现版本）。

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

• 规范版本（必须是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 支持用于更复杂的 API 版本配置的服务器变量模板。这看起来正是你要找的。但是，OpenAPI Generator 中的所有生成器尚未完全支持这些变量。如果您有特定的生成器，请为这些创建一个问题，因为最初的支持似乎只存在于 Ruby、PHP、python 和 JavaScript ES6 客户端生成器中。