OAS3指定的服务版本控制

Question

我们当前正在使用OpenAPI服务规范v3 OAS3指定新的REST服务API。由于种种原因，我们需要/想要从一开始就对服务API进行版本化（这是我们无法控制的因素所强制）。

我们要使用的版本控制方案是 URL路径版本-即类似.../v1/ourservice的内容。

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

到目前为止，我只在OAS3中看到了一个全局version属性-但是没有什么可以让我们轻松地在一个YAML文件中指定多个版本的（否则这是错误的方法） ？）。

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

Answer 1

Openp文档中的

version是指文档的版本，而不是API的版本。

来自the spec：

  

版本字符串 必需。 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支持server variable templating用于更复杂的API版本配置。这似乎正是您要寻找的。但是，尚未在OpenAPI Generator中的所有生成器中完全支持这些变量。如果您有特定的生成器，请使用open an issue，因为最初的支持似乎只存在于Ruby，PHP，python和JavaScript ES6客户端生成器中。