From 9e1ff6b04b4c5e206965662067153895d09670d7 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 19 Mar 2025 10:57:06 -0400 Subject: [PATCH 1/4] feat: adds a name field to the server object Signed-off-by: Vincent Biret --- src/oas.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) 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 From f1426811b08802842b0e48fe5ac96439ebec1c36 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 19 Mar 2025 11:03:45 -0400 Subject: [PATCH 2/4] chore: updates schema for server name field Signed-off-by: Vincent Biret --- src/schemas/validation/schema.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 3a8d2cb186..339417aed6 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, null] variables: type: object additionalProperties: From 49f43d405a8463fd213a687473ad191ec49e00bf Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 19 Mar 2025 12:16:46 -0400 Subject: [PATCH 3/4] Update src/schemas/validation/schema.yaml Co-authored-by: Ralf Handl --- src/schemas/validation/schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 339417aed6..3150952aa1 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -122,7 +122,7 @@ $defs: description: type: string name: - type: [string, null] + type: string variables: type: object additionalProperties: From 5ed147c9dcd95bcdd917d189f49ba050b3b7d886 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 19 Mar 2025 12:17:24 -0400 Subject: [PATCH 4/4] ci: adds a test value Signed-off-by: Vincent Biret --- tests/schema/pass/servers.yaml | 1 + 1 file changed, 1 insertion(+) 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.