OAS3指定了服务版本控制

Question

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

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

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

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

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

Answer 1

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

来自the spec：

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

所以，遗憾的是你需要关注三个版本。这是那些看起来像：

• 规范版本（必须是在https://github.com/OAI/OpenAPI-Specification定义的那个之一） 例：

oepnapi: 3.0.2

• 文件版本。我经常将此公开为自动生成的doc的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: [email protected]
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

• API版本。 有些人认为路径版本控制存在争议，但我们中的许多人（包括我自己）必须出于我们无法控制的各种原因而这样做。在所有规范版本中实现此目的的常用方法是在baseUrl中定义路径版本。例如，您的基本网址可能是/nested/v1或只是/v1。不幸的是，这只会涵盖v1方法。

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