Override “host” and “basePath” at the “/{path}” le

问题:

PROBLEM STATEMENT:

For a "strange" reason, all our operations of an API have different "host". We have API like this:

• operation 1: GET https://host1:port1/api/resources
• operation 2: GET https://host1:port2/api/resources/{id}
• operation 3: POST https://host2:port3/api/resources
• operation 4: POST https://host2:port4/api/resources/search

If we use Swagger/OpenAPI as it is, it means creating one Swagger/OpenAPI specification per operation, resulting having one swagger-ui page per operation, and then, the need to re-create an index page to list all the operations of an API :-/ which is exactly what we want to avoid.

QUESTIONS:

1/ Does this feature - Override "host" and "basePath" at the "/{path}" level - make sense?

2/ Does someone already try to implement this feature in swagger-ui?

3/ Could/should I propose this kind of change to OpenAPI?

Any other useful remarks/comments are welcome ;-)

回答1:

This is not supported in swagger 2.0 specification. It will be added in the next version though, so no need to add the proposal! See here:

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

回答2:

Overriding the target server at the path or operation level is now supported in 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: ...