有什么方法可以根据所选服务器更改 OpenAPI 规范中的值吗？

Question

在我的 OpenAPI 描述中，我定义了多个服务器，如下所示：

servers:
- url: /stuff/api/v1
  description: Production
- url: /api/v1
  description: Test

我们有一个托管 Swagger UI 的服务器（它引用我们的开放 API 规范文件来记录端点）。

在我们的服务器中，我们托管其他类型的文档（例如 PDF 文件或其他可下载内容）。 这些可以使用 Markdown 链接在我们的开放 API 规范文档中引用，并且在 Swagger UI 中呈现时允许用户单击链接并下载内容。

生产服务器位于几个代理后面，这意味着相对路径与我们在本地或测试服务器上运行时发生变化。

例如我希望 Markdown 链接如下：

[Something](relative/path/thing.txt)

如果 selected 服务器是 Test 服务器，以及类似

[Something](../foo/relative/path/thing.txt)

如果 selected 服务器是 Production。

就目前情况而言，我必须做这样的事情：

openapi: 3.0.0
info:
  title: My Endpoint
  version: '1.0'
  description: |
    ## Title
    Blah blah...

    ---
    [A File - PRODUCTION](../openapi/stuff/file.yaml)
    *(use this link if deployed in PRODUCTION)*

    [A File - TEST](openapi/stuff/file.yaml)
    *(use this link if deployed in TEST)*

Answer 1

您的问题不是很清楚您希望它们如何更改，但是您是否考虑过在服务器对象中使用

variables

？

它们可以在根、路径或操作中使用

根

openapi: 3.1.0
info:
  title: test
  version: 0.0.1
servers:
- url: https://{{domain}}.example.org/v1
  variables:
    domain:
      description: this is the domain variable
      enum:
      - prod
      - test
      default: prod
paths: {}

路径

openapi: 3.1.0
info:
  title: test
  version: 0.0.1
paths:
  '/thing':
    servers:
    - url: https://{{domain}}.example.org/v1
      variables:
        domain:
        description: this is the domain variable
        enum:
        - prod
        - test
        default: prod

操作

openapi: 3.1.0
info:
  title: test
  version: 0.0.1
paths:
  '/thing':
    get:
      servers:
      - url: https://{{domain}}.example.org/v1
        variables:
          domain:
          description: this is the domain variable
          enum:
          - prod4567
          - test
          default: prod4567
    post:
      servers:
      - url: https://{{domain}}.example.org/v1
        variables:
          domain:
          description: this is the domain variable
          enum:
          - prod123
          - test
          default: prod123