Linkオブジェクト

Linkオブジェクトは、応答に対する可能な設計時のリンクを表します。リンクの存在は、呼び出し元がリンクを正常に呼び出すことができることを保証するものではなく、応答と他の操作の間の既知の関係およびトラバーサル メカニズムを提供します。

*動的リンク (つまり、応答ペイロードで提供されるリンク)とは異なり、OAS リンク メカニズムは実行時応答にリンク情報を必要としません。

リンクを計算し、リンクを実行する命令を提供する場合、ランタイム式は、リンクされた操作の呼び出し中に操作内の値にアクセスし、それらの値をパラメーターとして使用するために使用されます。

固定フィールド

フィールド名	タイプ	説明
operationRef	string	OAS 操作への相対または絶対 URI 参照。このフィールドは operationIdフィールドとは相互に排他的であり、Operation Objectを指さなければなりません (MUST) 。OpenAPI 定義内の既存の操作オブジェクトを見つけるために相対operationRef値を使用してもよい。相対参照を解決するためのルールを参照してください。
operationId	string	一意のoperationId で定義された、解決可能な既存のOAS 操作の名前。このフィールドは、operationRefフィールドとは相互に排他的です。
parameters	Map[string, Any {expression}]	operationIdで指定された、または operationRefを介して識別された、操作に渡すパラメータを表すマップです。キーは使用するパラメータ名ですが、値は評価されてリンクされた操作に渡される定数または式になります。異なる場所で同じパラメータ名を使用する操作では、パラメータの場所 [{in}.]{name}を使用してパラメータ名を修飾できます(例: path.id)。
requestBody	任意 | {表現}	ターゲット操作を呼び出すときにリクエスト本文として使用するリテラル値または{expression} 。
description	string	リンクの説明。CommonMark 構文はリッチ テキスト表現に使用できます (MAY)。
server	Server Object	ターゲット操作で使用されるサーバー オブジェクト。

このオブジェクトは、仕様拡張機能を使用して拡張できます。

リンクされた操作は、operationRef またはoperationId のいずれかを使用して識別されなければなりません。operationIdの場合は、一意であり、OAS ドキュメントのスコープ内で解決される必要があります。名前が衝突する可能性があるため、このoperationRef構文は外部参照を含む OpenAPI ドキュメントに推奨されます。

例

リクエスト オペレーションからリンクを計算します。リンクされたオペレーションにリクエスト パラメータを渡すために$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

クライアントはすべてのリンクを自分の裁量でたどります。アクセス許可も、そのリンクへの呼び出しを成功させる機能も、関係の存在だけでは保証されません。

OperationRef の例

operationIdへの参照は不可能な場合がありますので ( operationIdはOperation Objectのオプションのフィールドです)、相対参照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 参照を使用する場合はエスケープされたスラッシュが必要であることに注意してください。

ランタイム式

ランタイム式を使用すると、実際の 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、tokenはRFC7230から引用されています。

識別子nameでは大文字と小文字が区別されますが、tokenは区別されません。

以下の表に、実行時式の例と、値でのそれらの使用例を示します。

例

ソースの場所	表現例	ノート
HTTPメソッド	$method	$methodに許容される値は、HTTP 操作の値になります。
要求されたメディアの種類	$request.header.accept
リクエストパラメータ	$request.path.id	リクエスト パラメータは親オペレーションのparametersセクションで宣言する必要があります。宣言しないと評価できません。これにはリクエスト ヘッダーが含まれます。
リクエストボディのプロパティ	$request.body#/user/uuid	ペイロードを受け入れる操作では、requestBody本体の一部または全体が参照される場合があります。
リクエストURL	$url
応答値	$response.body#/status	ペイロードを返す操作では、応答本文の一部または全体が参照されることがあります。
レスポンスヘッダー	$response.header.Server	単一ヘッダー値のみが使用可能です

実行時式は、参照される値の型を保持します。式を中括弧{}で囲むことにより、式を文字列値に埋め込むことができます。