OpenAPI 3.0 是否允许引用服务器变量？

Question

假设我的 OpenAPI 定义有两个服务器。两者共享相同的变量。因此我想引用这些变量以防止重复代码。

实际上，我将 OpenAPI 分成文件并将其与swagger-cli bundle. 这就是它创建的：

openapi: 3.0.2
info:
  title: My API
  description: 'some description'
  version: 1.0.0
servers:
  - url: 'https://stage-api.domain.com/foo/{v1}/{v2}/{v3}'
    description: Staging API server for QA
    variables:
      v1:
        description: 'variable 1'
        default: 'something'
        enum:
          - 'foo1'
          - 'foo2'
      v2:
        description: 'variable 2'
        default: 'something'
        enum:
          - 'foo1'
          - 'foo2'
      v3:
        description: 'variable 3'
        default: 'something'
        enum:
          - 'foo1'
          - 'foo2'
  - url: 'https://api.domain.com/foo/{v1}/{v2}/{v3}'
    description: PRODUCTION API server
    variables:
      region:
        $ref: '#/servers/0/variables/v1'
      brand:
        $ref: '#/servers/0/variables/v2'
      locale:
        $ref: '#/servers/0/variables/v3'
paths: {}

尝试在 Swagger Editor 中验证这一点时出现以下错误：

servers.1.variables.v1 处的结构错误不应该有附加属性additionalProperty: $ref 跳转到第xx行

servers.1.variables.v1 处的结构错误应该具有必需的属性“default”missingProperty: default 跳转到第 xx 行

是否可以引用服务器变量或以其他方式重用它们？

当然我可以运行swagger-cli bundle -r，但我想阻止使用它。

Answer 1

不，不支持此操作。您可以在https://github.com/OAI/OpenAPI-Specification/issues请求对 OpenAPI 规范进行更改

在您的示例中，除了子域之外，服务器路径几乎相同，因此您可以使用单个服务器定义并将子域设为变量：

servers:
  - url: 'https://{env}.domain.com/foo/{v1}/{v2}/{v3}'
    variables:
      env:
        description: Environment - staging or production
        default: stage-api
        enum:
          - stage-api
          - api
      # other variables
      # ...