在“/{path}”级别覆盖 "host" 和 "basePath"

Question

问题陈述：

由于"strange"的原因，我们对一个API的所有操作都有不同的"host"。我们有 API 这样的：

操作一：获取https://host1:port1/api/resources
操作2：获取https://host1:port2/api/resources/{id}
操作3：POST https://host2:port3/api/resources
操作4：POST https://host2:port4/api/resources/search

如果我们按原样使用 Swagger/OpenAPI，这意味着每个操作创建一个 Swagger/OpenAPI 规范，导致每个操作有一个 swagger-ui 页，然后，需要重新创建一个索引页面以列出 API :-/ 的所有操作，这正是我们想要避免的。

问题：

1/ 此功能 - 在“/{path}”级别覆盖 "host" 和 "basePath" - 有意义吗？

2/ 是否有人已经尝试在 swagger 中实现此功能-ui?

3/ Could/should 我建议这样改 OpenAPI?

欢迎任何其他有用的 remarks/comments ;-)

Answer 1

Swagger 2.0 规范不支持此功能。不过下个版本会加入，建议不用加了！看这里：

https://github.com/OAI/OpenAPI-Specification/issues/562

Answer 2

OpenAPI 3.0 现在支持在路径或操作级别覆盖目标服务器：

openapi: 3.0.0

servers:
  - url: https://my.api.com/v1

paths:
  /foo:
    # Override the server at path level
    servers:
      - url: https://another.server:8443/basePath

    get: ...
    post: ...

  /bar:
    get:
      # Override the server at operation level
      servers:
        - url: https://some.other.server/v2

    post: ...

在“/{path}”级别覆盖 "host" 和 "basePath"

Override "host" and "basePath" at the "/{path}" level

swagger

openapi