diff --git a/versions/3.0.md b/versions/3.0.md index dcaaeb57db..4413f1891d 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1173,7 +1173,8 @@ The `Link Object` is responsible for defining a possible operation based on a si Field Name | Type | Description ---|:---:|--- -href | url | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field. +href | url | a relative or absolute URL to a linked resource definition. This field is mutually exclusive with the `operationId` field. +url | url | a relative or absolute URL representing the target location for the link operation. This is used to override the `{scheme}://{host}/{basePath}` defined at the global level for the linked operation. 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. parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`. headers | Link Headers Object | an Object representing headers to pass to the linked resource. @@ -1184,6 +1185,23 @@ Locating a linked resource may be performed by either a `href` or `operationId`. In the case of an `operationId`, it must be unique and resolved in the scope of the OAS document. Because of the potential for name clashes, consider the `href` syntax as the preferred method for specifications with external references. +When the `url` attribute is provided, the target host may be overridden by the value provided. For example: + +``` +components: + links: + UserRepositories: + operationId: getRepositoriesByOwner + url: $responseHeaders.link + definitions: + user: + type: object +``` + +will extract the URL from the response header named `link`. If an absolute URL is provided, it will be used instead of the server / path provided in the target operation. Parameters _may_ be provided as well. If a `path` parameter is provided, it shall be ignored unless the `url` value contains a matching location for substitution. If query parameters are provided in the `url` value, they will be interpreted per the operation definition, and the absence of a required query parameter will result in an invalid request. + +When a relative path is provided in the `url` attribute, the host defined in the specification will be used. + #### Response Payload Values Payload values are only available in parseable response payloads which match the advertised media-type.