7

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

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

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

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

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

4

1 回答 1

7

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

从规格：

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

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

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 客户端生成器中。

于 2019-03-19T03:27:41.980 回答