OAS3指定的服务版本控制

Question

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

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

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

到目前为止，我只在version中看到了一个全局OAS3属性--但是没有任何东西允许我们在一个YAML文件中轻松地指定多个版本(或者这是一种错误的方式吗？)

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

Answer 1

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

来自规格

版本字符串需要。OpenAPI文档的版本(与OpenAPI规范版本或OpenAPI实现版本不同)。

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

• 规范版本(必须是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版本。 有些人认为path版本控制是有争议的，但是我们中的许多人(包括我自己)不得不这样做，原因很多是我们无法控制的。在所有规范版本中实现这一目标的一个常见方法是在baseUrl中定义路径版本。例如，您的基本URL可以是/nested/v1，也可以是简单的/v1。不幸的是，这只涉及v1方法。

对于更复杂的API版本配置，OAS3支持服务器变量模板。这看起来正是你要找的。但是，OpenAPI生成器中的所有生成器并不完全支持这些变量。如果考虑到特定的生成器，请使用公开问题，因为最初的支持似乎只存在于Ruby、python和JavaScript ES6客户机生成器中。