链接对象表示响应的可能设计时链接。链接的存在并不保证调用者能够成功调用它，而是提供了响应和其他操作之间已知的关联和遍历机制。与动态链接（即在响应有效负载中提供的链接）不同，OAS 链接机制不需要运行时响应中的链接信息。为了计算链接并提供执行它们的说明，使用运行时表达式来访问操作中的值并将其用作参数，同时调用链接的操作。

4.8.20.1 固定字段

字段名称	类型	描述
操作引用	字符串	到 OAS 操作的相对或绝对 URI 引用。此字段与operationId字段互斥，并且必须指向操作对象。相对operationRef值可以用于在 OpenAPI 定义中定位现有的操作对象。请参阅解析相对引用的规则。
操作ID	字符串	现有的可解析 OAS 操作的名称，由唯一的operationId定义。此字段与operationRef字段互斥。
参数	Map[string, Any  {表达式}]	表示要传递给操作的参数的映射，如使用operationId指定的或通过operationRef标识的参数。键是要使用的参数名称，而值可以是常量或要计算并传递给链接操作的表达式。参数名称可以使用参数位置[{in}.]{name}进行限定，用于在不同位置使用相同参数名称的操作（例如path.id）。
请求主体	Any  {表达式}	调用目标操作时用作请求主体的文字值或{表达式}。
描述	字符串	链接的描述。[CommonMark] 语法可以用于富文本表示。
服务器	服务器对象	目标操作要使用的服务器对象。

此对象*可以使用 规范扩展 进行扩展。

**链接的操作必须使用operationRef或operationId进行标识。在operationId的情况下，它必须在 OAS 文档的范围内是唯一的且可解析的。由于可能发生名称冲突，因此对于具有外部引用的 OpenAPI 文档，建议使用operationRef语法。

4.8.20.2 示例

计算来自请求操作的链接，其中$request.path.id用于将请求参数传递给链接的操作。

paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

当运行时表达式计算失败时，不会将任何参数值传递给目标操作。响应主体中的值可用于驱动链接的操作。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

客户端可自行决定是否遵循所有链接。仅凭关联关系的存在并不能保证权限或成功调用该链接的能力。

4.8.20.3 OperationRef 示例

由于对operationId的引用可能不可用（operationId是操作对象中的可选字段），因此也可以通过相对operationRef进行引用

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

或绝对operationRef

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
    parameters:
      username: $response.body#/username

请注意，在使用operationRef时，使用 JSON 引用时需要转义的正斜杠。

4.8.20.4 运行时表达式

运行时表达式允许根据仅在实际 API 调用中的 HTTP 消息内可用的信息来定义值。此机制由链接对象和回调对象使用。运行时表达式由以下[ABNF]语法定义

      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
      source = ( header-reference / query-reference / path-reference / body-reference )
      header-reference = "header." token
      query-reference = "query." name 
      path-reference = "path." name
      body-reference = "body" ["#" json-pointer ]
      json-pointer    = *( "/" reference-token )
      reference-token = *( unescaped / escaped )
      unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
      escaped         = "~" ( "0" / "1" )
        ; representing '~' and '/', respectively
      name = *( CHAR )
      token = 1*tchar
      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

这里，json-pointer取自[RFC6901]，char取自[RFC7159] 第 7 节，token取自[RFC7230] 第 3.2.6 节。

name标识符区分大小写，而token不区分大小写。

下表提供了运行时表达式的示例及其在值中用法的示例

4.8.20.5 示例

源位置	示例表达式	注释
HTTP 方法	$method	$method的允许值将是 HTTP 操作的值。
请求的媒体类型	$request.header.accept
请求参数	$request.path.id	请求参数必须在父操作的parameters部分中声明，否则无法计算它们。这包括请求标头。
请求主体属性	$request.body#/user/uuid	在接受有效负载的操作中，可以引用requestBody的部分或整个主体。
请求 URL	$url
响应值	$response.body#/status	在返回有效负载的操作中，可以引用响应主体的一部分或整个主体。
响应标头	$response.header.Server	仅提供单个标头值

运行时表达式保留引用的值的类型。表达式可以通过用{}花括号括起来的方式嵌入到字符串值中。