Openapi-specification: How should basePaths for multiple environments be specified?

[shelbys]

For instance, development vs test vs staging vs production?

We've been putting them in a parallel basePaths like:

{
  basePath: 'http://api.example.com'
  basePaths: {
    development: 'http://api.dev-example.com',
    test: 'http://api.test-example.com',
    stage: 'http://api.stage-example.com',
    production: 'http://api.example.com'
  }
}

[webron]

In Swagger 2.0 the definition of basePath has changed. It has been split to 3 properties - scheme, host and basePath. The basePath now becomes the actual base path which is relative to the host.
If the host is not specified, the basePath is taken against the host that's serving the specification.
Does this answer your need?

[lluu]

can you please describe the use case for 'scheme'?

[webron]

scheme is the transport protocol, either "http", or "https" (though "ws" and "wss" are also allowed). Again, if that is not specified, the one used to read the swagger.json will be used for API invocation.

[lluu]

I looked at https://github.com/wordnik/swagger-spec/blob/master/schemas/v2.0/schema.json and don't see the basePath structure you mentioned.. am i missing something here?? thx.

[webron]

https://github.com/wordnik/swagger-spec/blob/master/schemas/v2.0/schema.json#L25-L43

[lluu]

Thanks! Just making sure i understand how this works.
For example: my swagger.json url is http://host.co.com/myApi/swagger.json
say i have just
basePath=/
my request url, say for an invoice resource, would be http://host.co.com/invoice

however, if i have
basePath=/myApi
host=host2.co.com
scheme=https
my request url would be https://host2.co.com/myApi/invoice

[webron]

That is correct.

And as said, you can omit the host and scheme to allow for a more dynamic association should you need it. It can be especially useful when serving a static swagger.json rather than generating one.

Also, I didn't mention it before (though it's documented in the spec itself), host can also include a port in it.

[lluu]

excellent. Thanks.

[shelbys]

@webron - I don't think the new structure covers this, unless I'm missing something. How would I document four different environments in one spec file using the 2.0 syntax? Any of the three components (i.e. schema, host, and/or basePath) could be different for each environment. We try to only change the host, but I've seen the others as well

[webron]

@shelbys - it does not directly cover it. I'm just saying that if you don't include them, and host your swagger.json on each of those environment separately, you wouldn't need to change the basePath each time for the relevant environment.

We're working on a way to document several micro-services, but even there you'd need to duplicate your swagger.json with a different basePath. You'd have a centralized description though of the different environments.

[shelbys]

Grr, "Close" and "Comment" are too close together

@webron - We're specifically looking to document all of the environments in one place, so end-users know where they can try things out before hitting Prod. I think this is generally applicable, but particularly important when documenting APIs for other groups within an organization

[webron]

okay, let's revisit this once the micro services solution is published (should be within the next few days), and if it doesn't satisfy your needs, we'll mark it as a request for the next version.

[romandecker]

Has this been implemented now? I'm still confused on how to use different hosts for different environments. I only want to be able to use the same swagger.yaml file in development and in production, but have swagger-editor only go to development when I'm testing locally. Is this possible?

[webron]

Closing in favor of #562.

[leosoto]

@webron If I understand correctly from the resolution in #562 and the merged patch in #604, that won't allow to specify multiple global base paths based on "environments" as described at the beginning of this issue:

For instance, development vs test vs staging vs production?

The solution on #562 only supports overriding schema/host/past at the operation level. Shouldn't we reopen this ticket then? (Or perhaps closing it with the explicit reason that OpenAPI won't support this use case) cc: @fehguy

[webron]

@leosoto - we've decided that supporting environments is outside the scope.

[AmreeshTyagi]

@webron environment support is outside the scope. :( I was waiting for it since long time.