Cleaned up link examples
ADD
examples/v3.0/link-example.yaml
+openapi: 3.0.0
+info:
+ title: Link Example
+ version: 1.0.0
+paths:
+ /2.0/users/{username}:
+ get:
+ operationId: getUserByName
+ parameters:
+ - name: username
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: The User
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/user'
+ links:
+ userRepositories:
+ $ref: '#/components/links/UserRepositories'
+ /2.0/repositories/{username}:
+ get:
+ operationId: getRepositoriesByOwner
+ parameters:
+ - name: username
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: repositories owned by the supplied user
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/repository'
+ links:
+ userRepository:
+ $ref: '#/components/links/UserRepository'
+ /2.0/repositories/{username}/{slug}:
+ get:
+ operationId: getRepository
+ parameters:
+ - name: username
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: slug
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: The repository
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/repository'
+ links:
+ repositoryPullRequests:
+ $ref: '#/components/links/RepositoryPullRequests'
+ /2.0/repositories/{username}/{slug}/pullrequests:
+ get:
+ operationId: getPullRequestsByRepository
+ parameters:
+ - name: username
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: slug
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: state
+ in: query
+ schema:
+ type: string
+ enum:
+ - open
+ - merged
+ - declined
+ responses:
+ '200':
+ description: an array of pull request objects
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/pullrequest'
+ /2.0/repositories/{username}/{slug}/pullrequests/{pid}:
+ get:
+ operationId: getPullRequestsById
+ parameters:
+ - name: username
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: slug
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: pid
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: a pull request object
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/pullrequest'
+ links:
+ pullRequestMerge:
+ $ref: '#/components/links/PullRequestMerge'
+ /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge:
+ post:
+ operationId: mergePullRequest
+ parameters:
+ - name: username
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: slug
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: pid
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: the PR was successfully merged
+components:
+ links:
+ UserRepositories:
+ # returns array of '#/components/schemas/repository'
+ operationId: getRepositoriesByOwner
+ parameters:
+ username: $response.body#/username
+ UserRepository:
+ # returns '#/components/schemas/repository'
+ operationId: getRepository
+ parameters:
+ username: $response.body#/owner/username
+ slug: $response.body#/slug
+ RepositoryPullRequests:
+ # returns '#/components/schemas/pullrequest'
+ operationId: getPullRequestsByRepository
+ parameters:
+ username: $response.body#/owner/username
+ slug: $response.body#/slug
+ PullRequestMerge:
+ # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
+ operationId: mergePullRequest
+ parameters:
+ username: $response.body#/author/username
+ slug: $response.body#/repository/slug
+ pid: $response.body#/id
+ schemas:
+ user:
+ type: object
+ properties:
+ username:
+ type: string
+ uuid:
+ type: string
+ repository:
+ type: object
+ properties:
+ slug:
+ type: string
+ owner:
+ $ref: '#/components/schemas/user'
+ pullrequest:
+ type: object
+ properties:
+ id:
+ type: integer
+ title:
+ type: string
+ repository:
+ $ref: '#/components/schemas/repository'
+ author:
+ $ref: '#/components/schemas/user'

MODIFY
versions/3.0.md
versions/3.0.md
@@ -1892,7 +1892,7 @@ Field Name | Type | Description
---|:---:|---
<a name="linkOperationRef"></a>operationRef | `string` | a relative or absolute reference to an OAS operation. This field is mutually exclusive with the `operationId` field, and must point to the fragment of a valid OAS definition.
<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 with the `operationRef` field. Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OAS.
-<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.
+<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.
<a name="linkDescription"></a>description | `string` | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
<a name="linkServer"></a>server | [Server Object](#serverObject) | a server object to be used by the target operation.
@@ -1904,8 +1904,9 @@ Because of the potential for name clashes, consider the `operationRef` syntax as
method for specifications with external references.
-##### Request Parameter Example
-Computing a link from a request operation like this:
+##### Examples
+
+Computing a link from a request operation where the `$request.path.id` is used to pass a request parameter to the linked operation.
```yaml
paths:
@@ -1928,12 +1929,8 @@ paths:
uuid: the unique user id
type: string
format: uuid
-```
-
-Can be used in a link like this:
-
-```yaml
-Addresses:
+ links:
+ Address:
# the target link operationId
operationId: getUserAddress
parameters:
@@ -1941,247 +1938,30 @@ Addresses:
userId: $request.path.id
```
-Where the `$request.path.id` is the value passed in the request to `/users/{id}`.
When a runtime expression evaluates to null, no parameter value is passed to the target operation.
-##### Response Payload Example
+Values from the response body can be used to drive a linked operation.
```yaml
-AddressesLink:
+links:
+ addressesLink:
operationId: getUserAddressByUUID
parameters:
# get the `id` field from the request path parameter named `id`
userUuid: $response.body#/uuid
```
-And the array example:
-
-```yaml
-ColorSelectionLink:
- operationId: getColorSample
- parameters:
- colorName: $response.body#/color
-```
-
As with all links, it is at the clients' discretion to follow them, neither
permissions nor the ability to make a successful call to that link is guaranteed
solely by the existence of a relationship.
-
-##### Example
-
-The example below shows how relationships in the BitBucket API can be represented
-with the link schema. This example uses `operationId` values to link responses to
-possible operations.
-
-```yaml
-paths:
- /2.0/users/{username}:
- get:
- operationId: getUserByName
- parameters:
- - name: username
- in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: The User
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/user'
- links:
- userRepositories:
- $ref: '#/components/links/UserRepositories'
- /2.0/repositories/{username}:
- get:
- operationId: getRepositoriesByOwner
- parameters:
- - name: username
- in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: repositories owned by the supplied user
- content:
- application/json:
- schema:
- type: array
- items:
- $ref: '#/components/schemas/repository'
- links:
- userRepository:
- $ref: '#/components/links/UserRepository'
- /2.0/repositories/{username}/{slug}:
- get:
- operationId: getRepository
- parameters:
- - name: username
- in: path
- required: true
- schema:
- type: string
- - name: slug
- in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: The repository
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/repository'
- links:
- repositoryPullRequests:
- $ref: '#/components/links/RepositoryPullRequests'
- /2.0/repositories/{username}/{slug}/pullrequests:
- get:
- operationId: getPullRequestsByRepository
- parameters:
- - name: username
- in: path
- required: true
- schema:
- type: string
- - name: slug
- in: path
- required: true
- schema:
- type: string
- - name: state
- in: query
- schema:
- type: string
- enum:
- - open
- - merged
- - declined
- responses:
- '200':
- description: an array of pull request objects
- content:
- application/json:
- schema:
- type: array
- items:
- $ref: '#/components/schemas/pullrequest'
- /2.0/repositories/{username}/{slug}/pullrequests/{pid}:
- get:
- operationId: getPullRequestsById
- parameters:
- - name: username
- in: path
- required: true
- schema:
- type: string
- - name: slug
- in: path
- required: true
- schema:
- type: string
- - name: pid
- in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: a pull request object
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/pullrequest'
- links:
- pullRequestMerge:
- $ref: '#/components/links/PullRequestMerge'
- /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge:
- post:
- operationId: mergePullRequest
- parameters:
- - name: username
- in: path
- required: true
- schema:
- type: string
- - name: slug
- in: path
- required: true
- schema:
- type: string
- - name: pid
- in: path
- required: true
- schema:
- type: string
- responses:
- '204':
- description: the PR was successfully merged
-components:
- links:
- UserRepositories:
- # returns array of '#/components/schemas/repository'
- operationId: getRepositoriesByOwner
- parameters:
- username: $response.body#/username
- UserRepository:
- # returns '#/components/schemas/repository'
- operationId: getRepository
- parameters:
- username: $response.body#/owner/username
- slug: $response.body#/slug
- RepositoryPullRequests:
- # returns '#/components/schemas/pullrequest'
- operationId: getPullRequestsByRepository
- parameters:
- username: $response.body#/owner/username
- slug: $response.body#/slug
- PullRequestMerge:
- # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
- operationId: mergePullRequest
- parameters:
- username: $response.body#/author/username
- slug: $response.body#/repository/slug
- pid: $response.body#/id
- schemas:
- user:
- type: object
- properties:
- username:
- type: string
- uuid:
- type: string
- repository:
- type: object
- properties:
- slug:
- type: string
- owner:
- $ref: '#/components/schemas/user'
- pullrequest:
- type: object
- properties:
- id:
- type: integer
- title:
- type: string
- repository:
- $ref: '#/components/schemas/repository'
- author:
- $ref: '#/components/schemas/user'
-```
+##### OperationRef Examples
As references to `operationId` MAY NOT be possible (the `operationId` is an optional
value), references MAY also be made through a relative `operationRef`:
```yaml
-components:
links:
UserRepositories:
# returns array of '#/components/schemas/repository'
@@ -2193,7 +1973,6 @@ components:
or an absolute `operationRef`:
```yaml
-components:
links:
UserRepositories:
# returns array of '#/components/schemas/repository'
@@ -2205,36 +1984,11 @@ components:
Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when
using JSON references.
-```yaml
-paths:
- /user/{username}: # ...
- /user/{username}/commits:
- get:
- operationId: userCommitHistory
- parameters:
- - name: username
- in: path
- type: string
- required: true
- - name: page
- type: integer
- format: int32
- required: true
- responses: { ... }
-components:
- links:
- UserCommitHistory:
- operationId: userCommitHistory
- parameters:
- username: $response.body#/user/username
- page: 0
-```
-
-In the above, the link for `UserCommitHistory` points to the operation `getUserCommitHistory`, and passes the `username` value from the response payload as well as the static scalar value `0`.
##### <a name="runtimeExpression"></a>Runtime Expressions
-Runtime expressions allow defining values based on information that will only available within the HTTP message in an actual API call. This mechanism is used by [Link Parameters Objects](#linkParmeterObject) and [Callback Objects](#callbackObject).
+Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call.
+This mechanism is used by [Link Objects](#linkObject) and [Callback Objects](#callbackObject).
The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax

Cleaned up link examples