I've read upon the basePath spec of swagger from here. However, it seems that my current scenario is not among the ones listed here.

I need to basically:

• Use the same SCHEME and HOST as the location of where Swagger is currently hosted
• Dropdown with the version of API to be used as basePath

Scenario is:

• User accesses
• User then needs to just view a dropdown with the version of the API to be used as basepath (e.g. "/v1" or "/v2")

Reason is that the API is hosted on the same domain, so the API call will just work when they hit "Try it out" as long as a basePath is selected (or it defaults to the latest one, e.g. "v2").

Any idea on how the "servers" property would look like in such a scenario?

I've tried multiple times and I can't seem to work it out.

I am using the YAML format, so no code-builders or anything.

I've read upon the basePath spec of swagger from here. However, it seems that my current scenario is not among the ones listed here.

I need to basically:

• Use the same SCHEME and HOST as the location of where Swagger is currently hosted
• Dropdown with the version of API to be used as basePath

Scenario is:

• User accesses https://their_company_subdomain.myapp/swagger
• User then needs to just view a dropdown with the version of the API to be used as basepath (e.g. "/v1" or "/v2")

Reason is that the API is hosted on the same domain, so the API call will just work when they hit "Try it out" as long as a basePath is selected (or it defaults to the latest one, e.g. "v2").

Any idea on how the "servers" property would look like in such a scenario?

I've tried multiple times and I can't seem to work it out.

I am using the YAML format, so no code-builders or anything.

• swagger
• openapi
• swagger-2.0

1 Answer 1

In OpenAPI 3.x, servers[].url can be relative, in which case it's resolved against the location of the OpenAPI file (not the location of the docs page that renders the OpenAPI file).

You can use:

openapi: 3.1.1

servers:
  - url: /v1
  - url: /v2

paths:
  /something:
    ...

Assuming the OpenAPI file lives at

https://their_company_subdomain.myapp/path/to/openapi.yaml

the API server paths resolve to

https://their_company_subdomain.myapp/v1
https://their_company_subdomain.myapp/v2

and the endpoint path resolves to

https://their_company_subdomain.myapp/v1/something
https://their_company_subdomain.myapp/v2/something

OpenAPI renderers that support multiple servers will display a dropdown for users to select the target server. For example, here's how it looks in Swagger UI: