Skip to content

Commit d5c3c59

Browse files
authored
Merge pull request #3883 from handrews/link-param-311
Clarify Link Obj parameters as best we can (3.1.1 port of #3824)
2 parents f9923f9 + eb62785 commit d5c3c59

File tree

1 file changed

+4
-1
lines changed

1 file changed

+4
-1
lines changed

versions/3.1.1.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2147,7 +2147,7 @@ Field Name | Type | Description
21472147
---|:---:|---
21482148
<a name="linkOperationRef"></a>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. See the rules for resolving [Relative References](#relativeReferencesURI).
21492149
<a name="linkOperationId"></a>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.
2150-
<a name="linkParameters"></a>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).
2150+
<a name="linkParameters"></a>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.
21512151
<a name="linkRequestBody"></a>requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation.
21522152
<a name="linkDescription"></a>description | `string` | A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
21532153
<a name="linkServer"></a>server | [Server Object](#serverObject) | A server object to be used by the target operation.
@@ -2159,6 +2159,9 @@ In the case of an `operationId`, it MUST be unique and resolved in the scope of
21592159
Because of the potential for name clashes, the `operationRef` syntax is preferred
21602160
for OpenAPI documents with external references.
21612161

2162+
Note that it is not possible to provide a constant value to `parameters` that matches the syntax of a runtime expression.
2163+
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).
2164+
21622165
##### Examples
21632166

21642167
Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation.

0 commit comments

Comments
 (0)