-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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
Experiments with templated hosts #779
Comments
Hmm, the |
@ePaul I suppose it would. Do we really want to have to specify the parameter in every operation though? Even if we $ref it, it is still a pain. |
Hmm, good point. But didn't we have global (or at least path-level) parameters too? |
Open 3.0 does have path item parameters, which is a bit less redundant than operation parameters, but still a little annoying. How do you feel about defining a parameters object inside a hosts/server object? |
In option 2, should Also, I think the "server" element name is also a bit misleading since it is a URL not just a server. I suggest using
|
Is there some additional background material on this proposal -what is the motivation/use case and what is the problem this solves? For example, how are the default values overridden? Can I open an Open API spec in the UI and set I suggest considering profiles , where a profile is a collection of parameter names/values. associated with values for these parameters (i.e. version 1.0, version 1.1, version 2.0) or for example dev/test/prod profiles to referencing the same API on dev, test, and prod servers. A specific profile may need to set more than just one variable such as |
@david Yes, using in:host is misleading, however, it was a continuation of the current state of OpenApi 3.0 where "hosts" is a top level element that contains "hosts", "basePath" and "scheme". The issues we are trying to address are mainly those brought up in issue #169. If I were to try and distill the intent to a single sentence, I would say: That by allowing parameters in the baseUrl we can use a single OpenAPI specification to access multiple implementations of the HTTP interface it describes. The idea of parameter |
@darrelmiller I've thought through this, here is my take.
With that, I'm suggesting we not try to reuse the
That would produce something like this: server:
url: {scheme}://{environment}.gigantic-server.com/{base}
templateParameters: # <== let's choose a different name?
scheme:
enum:
- http
- https
default: https
environment: # no enum, so accept anything
default: development
base:
enum:
- /v1
- /v2
default: /v2 This ends up being nice an concise. In the degenerate case: server:
url: http://petstore.gigantic-server.com/v2 |
+1 to @fehguy's assertion that the The problem being solved here is that any given environment should be able to change the server URL. As such, environment should be a top-level key with template params under it. Refining @fehguy 's example, with what I think is more realistic usage: server:
url: "{scheme}://{host}:{port}/{base}"
defaultTemplate: development
templates: // effectively 'environments' in practice
development:
scheme:
default: http
host:
default: development.gigantic-server.com
port:
enum:
- 8080
- 8088
default: 8080
base:
default: v2
production:
scheme:
default: http
enum:
- http
- https
host:
default: api.gigantic-server.com
port:
default: 80
base:
default: v2
enum:
- v1
- v2 Default (aka degenerate) case: server:
url: http://development.gigantic-server.com:8080/v2 |
Goofy comment up front: We could punt on all of this if we told people to put their OpenAPI document at the root of their API. Then we could make discovery a problem for APIs.json Now back to sad reality. I don't think environments should be the primary use case of this feature. I think things like language, tenant and version are uses. Should we really be encouraging people to be advertising the location of their development environment in their publicly facing OpenAPI document? |
@darrelmiller In many cases I've seen the OpenAPI document being copied into the source code of a client, and then code generation (swagger-codegen or similar) being run on it. Now we either need to do a separate build for the development environment (and copy two files, which can easily go out of sync), override the URL for the dev version (or ignore the URL in the API definition and just take it from some configuration), or do some other hack. |
Thanks @jharmn, @ePaul and @darrelmiller. I'm going to combine these thoughts into #812 |
Since #812 was merged, I'm closing this out. |
On the TDC call today, we experimented with a few different options for enabling parameterized host, schema and basePath. Community feedback would be much appreciated.
Option 1: Global parameters are back
This is a minimally intrusive option but it brings the
parameters
back at the global scope which we are not particularly keen to do.The next option trades the current array of
hosts
into aserver
object so that it can contain thehost
related parameters. It also means that there is only one baseUrl, but it can be parameterized and in fact the entire thing could be a parameter, which could allow for multiple static values using an enum parameter.There are concerns about how
default
values work in these parameters and the"in" : "host"
is redundant but there just for consistency with the parameter object definition.The text was updated successfully, but these errors were encountered: