Experiments with templated hosts

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.

[darrelmiller]

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?

[fehguy]

Since #812 was merged, I’m closing this out.