Updates to link object and link parameter objects
MODIFY
versions/3.0.md
versions/3.0.md
@@ -1860,25 +1860,20 @@ The presence of a link does not guarantee the caller's ability to successfully i
As opposed to _dynamic_ links (links provided **in** the response payload), the OAS linking mechanism does not require that link information be provided in a specific response format at runtime.
-For computing links, and providing instructions to execute them, a mechanism is defined for accessing values in a response and using them as variables while invoking the linked operation.
-
-Field Name | Type | Description
----|:---:|---
-<a name="referenceRef"></a>$ref | `string` | If present, a reference to another Links Object. Note, the presence of `$ref` in the Links Object will cause all _Patterned Objects_ to be ignored.
+For computing links, and providing instructions to execute them, [variable substitution](#variableSubstitution) is used for accessing values in a response and using them as values while invoking the linked operation.
Field Pattern | Type | Description
---|:---:|---
-<a name="linkName"></a>link name | [Link Object](#linkObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject).
+<a name="linkName"></a> {name} | [Link Object](#linkObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject).
The link SHALL reference a single Link Object, or a JSON Reference to a single link object.
-
#### <a name="#linkObject"></a>Link Object
The `Link Object` is responsible for defining a possible operation based on a single response.
Field Name | Type | Description
---|:---:|---
href | `string` | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field.
-operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `href` field. Relative `href` values MAY be used to locate an existing Operation Object in the OAS.
+operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive with the `href` field. Relative `href` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS.
parameters | [Link Parameters Object](#linkParametersObject) | an object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
headers | [Headers Object](#headersObject) | an object representing headers to pass to the linked resource. Where conflicts occur between these headers, and those defined in the related operation, these headers override.
description | `string` | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
@@ -2053,9 +2048,10 @@ paths:
operationId: getUserByName
parameters:
- name: username
- type: string
in: path
required: true
+ schema:
+ type: string
responses:
200:
description: The User
@@ -2071,9 +2067,10 @@ paths:
operationId: getRepositoriesByOwner
parameters:
- name: username
- type: string
in: path
required: true
+ schema:
+ type: string
responses:
200:
description: repositories owned by the supplied user
@@ -2094,10 +2091,13 @@ paths:
type: string
in: path
required: true
- - name: slug
+ schema:
type: string
+ - name: slug
in: path
required: true
+ schema:
+ type: string
responses:
200:
description: The repository
@@ -2113,16 +2113,19 @@ paths:
operationId: getPullRequestsByRepository
parameters:
- name: username
- type: string
in: path
required: true
- - name: slug
+ schema:
type: string
+ - name: slug
in: path
required: true
- - name: state
+ schema:
type: string
+ - name: state
in: query
+ schema:
+ type: string
enum:
- open
- merged
@@ -2141,17 +2144,20 @@ paths:
operationId: getPullRequestsById
parameters:
- name: username
- type: string
in: path
required: true
- - name: slug
+ schema:
type: string
+ - name: slug
in: path
required: true
- - name: pid
+ schema:
type: string
+ - name: pid
in: path
required: true
+ schema:
+ type: string
responses:
200:
description: a pull request object
@@ -2166,17 +2172,20 @@ paths:
operationId: mergePullRequest
parameters:
- name: username
- type: string
in: path
required: true
- - name: slug
+ schema:
type: string
+ - name: slug
in: path
required: true
- - name: pid
+ schema:
type: string
+ - name: pid
in: path
required: true
+ schema:
+ type: string
responses:
204:
description: the PR was successfully merged
@@ -2262,6 +2271,10 @@ Many operations require parameters to be passed, and these MAY be dynamic depend
To specify parameters required by the operation, we can use a **Link Parameters Object**.
This object contains parameter names along with static or dynamic values:
+Field Pattern | Type | Description
+---|:---:|---
+<a name="linkParameterName"></a> {name} | Any <span>&#124;</span> [{expression}](#variableSubstitution) | A constant value or expression to be evaluated and passed to the linked operation.
+
```yaml
paths:
/user/{username}: # ...

Updates to link object and link parameter objects