diff --git a/src/oas.md b/src/oas.md index 19d26b27c0..1737af40b9 100644 --- a/src/oas.md +++ b/src/oas.md @@ -477,6 +477,7 @@ An object representing a Server. | ---- | :----: | ---- | | 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 document containing the Server Object is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. | | 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. | +| name | `string` | An optional unique string to refer to the host designated by the URL. | | variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. | This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -488,13 +489,15 @@ A single server would be described as: ```json { "url": "https://development.gigantic-server.com/v1", - "description": "Development server" + "description": "Development server", + "name": "dev" } ``` ```yaml url: https://development.gigantic-server.com/v1 description: Development server +name: dev ``` The following shows how multiple servers can be described, for example, at the OpenAPI Object's [`servers`](#oas-servers): @@ -504,15 +507,18 @@ The following shows how multiple servers can be described, for example, at the O "servers": [ { "url": "https://development.gigantic-server.com/v1", - "description": "Development server" + "description": "Development server", + "name": "dev" }, { "url": "https://staging.gigantic-server.com/v1", - "description": "Staging server" + "description": "Staging server", + "name": "staging" }, { "url": "https://api.gigantic-server.com/v1", - "description": "Production server" + "description": "Production server", + "name": "prod" } ] } @@ -522,10 +528,13 @@ The following shows how multiple servers can be described, for example, at the O servers: - url: https://development.gigantic-server.com/v1 description: Development server + name: dev - url: https://staging.gigantic-server.com/v1 description: Staging server + name: staging - url: https://api.gigantic-server.com/v1 description: Production server + name: prod ``` The following shows how variables can be used for a server configuration: @@ -536,6 +545,7 @@ The following shows how variables can be used for a server configuration: { "url": "https://{username}.gigantic-server.com:{port}/{basePath}", "description": "The production API server", + "name": "prod", "variables": { "username": { "default": "demo", @@ -558,6 +568,7 @@ The following shows how variables can be used for a server configuration: servers: - url: https://{username}.gigantic-server.com:{port}/{basePath} description: The production API server + name: prod variables: username: # note! no enum here means it is an open value diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 3a8d2cb186..3150952aa1 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -121,6 +121,8 @@ $defs: type: string description: type: string + name: + type: string variables: type: object additionalProperties: diff --git a/tests/schema/pass/servers.yaml b/tests/schema/pass/servers.yaml index 77a20498da..02e067a629 100644 --- a/tests/schema/pass/servers.yaml +++ b/tests/schema/pass/servers.yaml @@ -6,5 +6,6 @@ paths: {} servers: - url: /v1 description: Run locally. + name: local - url: https://production.com/v1 description: Run on production server.