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

Question

问题陈述：

由于某种“奇怪”的原因，我们所有的API操作都有不同的“主机”。我们有如下API：

• 操作1：GET https://host1:port1/api/resources
• 操作2：GET 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}”级别上覆盖“主机”和“basePath”是否有意义？

2/ 是否有人已经尝试在swagger-ui中实现这个功能？

3/ 我能/应该向OpenAPI提出这种改变吗？

欢迎提出任何其他有用的意见/评论 ;-)

- Babelabout

Answer 1

在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: ...

- Helen

Answer 2

这在Swagger 2.0规范中不受支持。但它将会在下一个版本中加入，所以无需添加提议！请在此处查看：

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

- fehguy

---

太好了！而且，我发现我在请求中显然错过的“方案”（schemes）甚至已经在那里;-) 你知道是否可以已经找到一个新版本的swagger-ui，将这个变化考虑进去了吗？ - Babelabout