From 6a0ed25d96fb709b4533f6fde540717f82aa2e30 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 23 May 2024 18:10:00 -0700 Subject: [PATCH 1/2] Clarify Link Obj parameters as best we can (3.0.4) This acknowledges the ambiguity in the key and value syntax of the Link Object's `parameter` field, and provides a bit of guidance on how to implement it. Sadly it is not possible to fully solve in a point release. --- versions/3.0.4.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 12b2375a79..0720ad67a8 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -2073,7 +2073,7 @@ Field Name | Type | Description ---|:---:|--- operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OpenAPI definition. operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. -parameters | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path\.id). +parameters | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used (optionally qualified with the parameter location, e.g. `path.id` for an `id` parameter in the path), whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation. description | `string` | A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. server | [Server Object](#serverObject) | A server object to be used by the target operation. @@ -2085,6 +2085,9 @@ In the case of an `operationId`, it MUST be unique and resolved in the scope of Because of the potential for name clashes, the `operationRef` syntax is preferred for specifications with external references. +Note that it is not possible to provide a constant value to `parameters` that matches the syntax of a runtime expression. +It is possible to have an ambiguous parameter names, e.g. `name: id, in: path` and `name: path.id, in: query`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query paramter). +I ##### Examples Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation. From abd448521ec6fbfbfa1306a9d6612b30b3acd7cd Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 24 May 2024 12:15:23 -0700 Subject: [PATCH 2/2] Fix grammar (review feedback) Co-authored-by: Ralf Handl --- versions/3.0.4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 0720ad67a8..cb9427d708 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -2086,8 +2086,8 @@ Because of the potential for name clashes, the `operationRef` syntax is preferre for specifications with external references. Note that it is not possible to provide a constant value to `parameters` that matches the syntax of a runtime expression. -It is possible to have an ambiguous parameter names, e.g. `name: id, in: path` and `name: path.id, in: query`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query paramter). -I +It is possible to have ambiguous parameter names, e.g. `name: id, in: path` and `name: path.id, in: query`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query paramter). + ##### Examples Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation.