Skip to content

Clarify server variables (Addresses #1675) #2140

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.

Sign up for GitHub

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

Closed
wants to merge 2 commits into from
Closed

Clarify server variables (Addresses #1675) #2140

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
31a1214
Fixes #1675. Clarifies the language around server variables to make i…
tedepstein Feb 15, 2020
51bb8bc
#1675 - Small tweaks to Server Variable language.
tedepstein Feb 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions versions/3.0.3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,15 +317,15 @@ url: https://www.apache.org/licenses/LICENSE-2.0.html

#### <a name="serverObject"></a>Server Object

An object representing a Server.
An object representing a single server or a group of servers sharing a common URL structure.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case Server Object represents a logical origin server, not whether there is one more physical machines. Saying that server could mean one or more is not really adding any clarity in my opinion. Once server variables are resolved it only points to one logical server.


##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
<a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL may include variable expressions, delimited by `{`curly braces`}`. Each variable expression MUST correspond to a [Server Variable Object](#serverVariableObject) named in the `variables` field, and the API consumer MUST replace each variable expression with a with a valid value, as specified by the corresponding Server Variable Object. The URL MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should not talk about how to resolve relative URLs here. We have a dedicated paragraph for that. We could link to it.

<a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="serverVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template.
<a name="serverVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a server variable name and a Server Variable Object. Each server variable name SHOULD be referenced by a variable expression in the `url`.
Copy link
Contributor Author

@tedepstein tedepstein Feb 15, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... not disallowing unused server variables. But server variables don't serve any purpose unless they're used. In an editor, a warning on an unused server variable might alert the user to an oversight, so I thought it'd be useful to note this here, with the SHOULD clause.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather not include the last sentence. I don't want to set the precedent that everywhere we have something that can be used we have to state where it can be used.


This object MAY be extended with [Specification Extensions](#specificationExtensions).

Expand Down Expand Up @@ -387,7 +387,7 @@ The following shows how variables can be used for a server configuration:
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
"description": "A user-specific subdomain provisioned for each account. Use `demo` for a free sandbox environment."
},
"port": {
"enum": [
Expand All @@ -413,7 +413,9 @@ servers:
username:
# note! no enum here means it is an open value
default: demo
description: this value is assigned by the service provider, in this example `gigantic-server.com`
description: |
A user-specific subdomain provisioned for each account.
Use `demo` for a free sandbox environment.
port:
enum:
- '8443'
Expand All @@ -427,14 +429,16 @@ servers:

#### <a name="serverVariableObject"></a>Server Variable Object

An object representing a Server Variable for server URL template substitution.
An object representing a Server Variable for URL template substitution in a containing [Server Object](#serverObject).

To form an addressable server URL, the API consumer MUST substitute a valid value for each variable expression in the Server Object's `url` template. The API consumer MAY assign Server Variable values from user input, configuration settings, or any other source. If the API consumer does not have an assigned value for a given server variable, it MUST substitute the provided `default` value.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Up-front summary of the basic workings.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The second paragraph is great content for a best practices documentation. I don't believe the spec the right place to include detailed usage guidance. We need to limit the text to constraints that tooling must/should respect.


##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty.
<a name="serverVariableDefault"></a>default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional. If the [`enum`](#serverVariableEnum) is defined, the value SHOULD exist in the enum's values.
<a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of valid string values for this variable. The array SHOULD NOT be empty. If `enum` is specified, the API consumer MUST assign one of enumerated values to the server variable.
<a name="serverVariableDefault"></a>default | `string` | **REQUIRED**. The default value for the server variable. If [`enum`](#serverVariableEnum) is defined, the `default` value SHOULD exist in the enum's values. If the API consumer does not have an alternative value, it MUST substitute the `default` value. Note that this behavior is different from the [Schema Object's](#schemaObject) treatment of default values. Schema defaults can be resolved by the server, and MAY be omitted from the request; but Server Variables MUST be resolved to an assigned or default value by the client, to assemble a final URL for the API request.
<a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.

This object MAY be extended with [Specification Extensions](#specificationExtensions).
Expand Down