6

问题陈述：

出于“奇怪”的原因，我们对 API 的所有操作都有不同的“主机”。我们有这样的 API：

  • 操作 1：获取 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/ 我可以/应该对 OpenAPI 提出这种改变吗？

欢迎任何其他有用的评论/评论;-)

4

2 回答 2

7

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: ...
于 2018-03-15T12:11:45.077 回答
4

这在 swagger 2.0 规范中不受支持。不过会在下个版本中添加，所以不需要添加提案！看这里：

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

于 2016-05-12T16:55:38.557 回答