Skip to content

Experiments with templated hosts #779

Closed
@darrelmiller

Description

@darrelmiller

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions