Description
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
{
"openapi" : "3.0.0",
"parameters" : {
"version" : {
"in" : "basepath",
"default" : "v1.0",
"schema" : {
"type" : "string"
}
},
"environment" : {
"in" : "host",
"required" : true,
"schema" : {
"type" : "string"
}
}
},
"hosts" : [
{
"host" : "{environment}.example.org",
"basePath" : "/{version}/api",
"scheme" : "https"
}
]
}
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 a server
object so that it can contain the host
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.
{
"openapi" : "3.0.0",
"server" : {
"baseUrl" : "{scheme}://{environment}.example.org/{version}/api",
"parameters" : [
{
"name" : "scheme",
"in" : "host",
"default" : "https",
"schema" : {
"type" : "string"
}
},
{
"name" : "version",
"in" : "host",
"required" : false,
"default" : "v1.0",
"schema" : {
"type" : "string"
}
},
{
"name" : "environment",
"in" : "host",
"required" : true,
"schema" : {
"type" : "string"
}
}
]
}
}
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.