Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify Link Obj parameters as best we can (3.1.1 port of #3824) #3883

Merged
merged 1 commit into from
Jun 6, 2024
Merged

Clarify Link Obj parameters as best we can (3.1.1 port of #3824) #3883

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion versions/3.1.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2147,7 +2147,7 @@ Field Name | Type | Description
---|:---:|---
<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).
<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.
<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).
<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.
<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.
<a name="linkDescription"></a>description | `string` | A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
<a name="linkServer"></a>server | [Server Object](#serverObject) | A server object to be used by the target operation.
Expand All @@ -2159,6 +2159,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 OpenAPI documents 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 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.
Expand Down