From 84b40efd58c0ccecc6b125dd47a8e89e29f4faa9 Mon Sep 17 00:00:00 2001 From: Ted Epstein Date: Wed, 6 Feb 2019 10:42:27 -0500 Subject: [PATCH 1/3] Proposed fix for #1830. Each variable expression in a path must have a corresponding path parameter. --- versions/3.0.3.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index fd83740826..5bfdd48b56 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -71,7 +71,9 @@ An OpenAPI definition can then be used by documentation generation tools to disp A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating -Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters. +Path templating refers to the usage of variable expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. + +Each variable expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). ##### Media Types Media type definitions are spread across several resources. @@ -1010,7 +1012,7 @@ There are four possible parameter locations specified by the `in` field: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. +name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. From 7a61f246608c5e10c31093f3c6bea36f588c7cca Mon Sep 17 00:00:00 2001 From: Ted Epstein Date: Wed, 6 Feb 2019 12:01:35 -0500 Subject: [PATCH 2/3] #1830 - Removed 'at least once' to defer the question about repeated references to a single path parameter. --- versions/3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 5bfdd48b56..49711e2f35 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -1012,7 +1012,7 @@ There are four possible parameter locations specified by the `in` field: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. +name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*. in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. From 6929fee75b86f31303d97e70760798819ff3977b Mon Sep 17 00:00:00 2001 From: Ted Epstein Date: Wed, 12 Feb 2020 13:33:36 -0500 Subject: [PATCH 3/3] Update #1830 fix with suggestion from Darrel @darrelmiller suggestions we use "template expression" instead of "variable expression" to align with RFC6570. Good idea. --- versions/3.0.3.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 49711e2f35..e02b36fbec 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -71,9 +71,9 @@ An OpenAPI definition can then be used by documentation generation tools to disp A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification. ##### Path Templating -Path templating refers to the usage of variable expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. +Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. -Each variable expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). +Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). ##### Media Types Media type definitions are spread across several resources. @@ -1012,7 +1012,7 @@ There are four possible parameter locations specified by the `in` field: ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a variable expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
+name | `string` | **REQUIRED**. The name of the parameter. Parameter names are *case sensitive*.
  • If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to a template expression occurring within the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.
  • If [`in`](#parameterIn) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.
  • For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameterIn) property.
in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"header"`, `"path"` or `"cookie"`. description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation. required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is `"path"`, this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.