Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How should basePaths for multiple environments be specified? #106

Closed
shelbys opened this issue Sep 12, 2014 · 17 comments
Closed

How should basePaths for multiple environments be specified? #106

shelbys opened this issue Sep 12, 2014 · 17 comments

Comments

@shelbys
Copy link

shelbys commented Sep 12, 2014

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
Copy link
Member

webron commented Sep 19, 2014

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
Copy link

lluu commented Sep 19, 2014

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

@webron
Copy link
Member

webron commented Sep 19, 2014

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
Copy link

lluu commented Sep 19, 2014

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.

@lluu
Copy link

lluu commented Sep 19, 2014

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
Copy link
Member

webron commented Sep 19, 2014

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
Copy link

lluu commented Sep 19, 2014

excellent. Thanks.

@shelbys
Copy link
Author

shelbys commented Sep 19, 2014

@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
Copy link
Member

webron commented Sep 20, 2014

@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 shelbys closed this as completed Sep 22, 2014
@shelbys shelbys reopened this Sep 22, 2014
@shelbys
Copy link
Author

shelbys commented Sep 22, 2014

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
Copy link
Member

webron commented Sep 22, 2014

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.

wting pushed a commit to wting/swagger-spec that referenced this issue Oct 21, 2014
@romandecker
Copy link

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
Copy link
Member

webron commented Mar 27, 2016

Closing in favor of #562.

@webron webron closed this as completed Mar 27, 2016
@leosoto
Copy link

leosoto commented Apr 24, 2016

@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
Copy link
Member

webron commented May 19, 2016

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

@AmreeshTyagi
Copy link

AmreeshTyagi commented Jun 14, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants