updated to support alternate link URLs, for #783

Author: fehguy

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.
+
 #### <a name="responsePayload"></a>Response Payload Values
 
 Payload values are only available in parseable response payloads which match the advertised media-type.