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编辑器中对此进行验证时，出现以下错误：

servers.1.variables.v1中的结构错误不应包含   其他属性AdditionalProperty：$ ref跳至第xx行

servers.1.variables.v1上的结构错误应该是必需的   属性'default'missingProperty：默认跳至第xx行

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

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

Answer 1

否，不支持此操作。您可以在以下位置请求对OpenAPI规范的更改：
https://github.com/OAI/OpenAPI-Specification/issues

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

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
      # ...

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

1 个答案: