Skip to content

Add link support from urls #3269

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

Closed
wants to merge 1 commit into from
Closed

Add link support from urls #3269

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
23 changes: 18 additions & 5 deletions versions/3.2.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2031,6 +2031,10 @@ Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OA

For computing links, and providing instructions to execute them, a [runtime expression](#runtimeExpression) is used for accessing values in an operation and using them as parameters while invoking the linked operation.

Clients follow all links at their discretion.
Neither permissions, nor the capability to make a successful call to that link, is guaranteed
solely by the existence of a relationship.

Copy link
Contributor Author

@mikekistler mikekistler May 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved this text from within the first example description to the main description of the Link Object to indicate that it applies generally and not just to that specific example.

##### Fixed Fields

Field Name | Type | Description
Expand All @@ -2039,6 +2043,7 @@ Field Name | Type | Description
<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="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="linkUrl"></a>url | Any \| {expression} | A constant or an expression to be evaluated and passed to the linked operation. The value should be a URL for the linked operation. Applications may extract values for path or query parameters present in this URL to use as values for these parameters in the linked operation.
Copy link
Member

@darrelmiller darrelmiller May 11, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<a name="linkUrl"></a>url | Any \| {expression} | A constant or an expression to be evaluated and passed to the linked operation. The value should be a URL for the linked operation. Applications may extract values for path or query parameters present in this URL to use as values for these parameters in the linked operation.
<a name="linkUrl"></a>url | `string` \| {expression} | A constant or an expression to be evaluated and passed to the linked operation. The value SHOULD evaluate to be a URL that matches? the linked operation. Applications may extract values for path or query parameters present in this URL to use as values for these parameters in the linked 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 Down Expand Up @@ -2112,11 +2117,6 @@ links:
userUuid: $response.body#/uuid
```

Clients follow all links at their discretion.
Neither permissions, nor the capability to make a successful call to that link, is guaranteed
solely by the existence of a relationship.


##### OperationRef Examples

As references to `operationId` MAY NOT be possible (the `operationId` is an optional
Expand Down Expand Up @@ -2145,6 +2145,19 @@ links:
Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when
using JSON references.

##### URL Examples

The `url` field can be used to specify a literal value or an expression containing a relative or absolute
URL to use for the target operation. A common example of this scenario is the "Location" header returned in a 201 response from POST.

```yaml
links:
ResourceLocation:
operationId: getUser
url: $response.header.location
```

Clients may use the evaluated value directly or as the source of path or query parameter values for the linked operation.

##### <a name="runtimeExpression"></a>Runtime Expressions

Expand Down