1. Homepage
  2. DataGraph
  3. DataGraph CLI および API 拡張機能の使用

  4. DataGraph の API 拡張機能

Anypoint DataGraph API 拡張機能リファレンス

このガイドでは、DataGraph の API 拡張機能を定義します。

オブジェクト種別拡張機能

この拡張機能により、オブジェクト種別に主キーがあり、リファレンスまたは拡張機能として使用できることがマークされます。

この拡張機能は、​ObjectType​ に適用されます。

構造

項目 型 説明

entity

Map (マップ)

オブジェクト種別をエンティティとしてマークします。

entity.key

String (文字列)

空にできない配列。各項目は、エンティティのキーである項目を参照する必要があります。

OAS の例

components:
  schemas:
    Customer:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  email:
          type: string
    	  id:
          type: string
    	  ...

RAML の例

types:
  Customer:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	email:
        type: string
    	id:
        type: string
    	...

エンティティリファレンス

この拡張機能により、1 つの種別から別の種別への DataGraph ​リンク​が生成されます。リンクは、同じ API 仕様で定義されない種別にできます。

この拡張機能は、​ObjectType​ に適用されます。

構造

項目 型 説明

entity-reference

オブジェクトの配列

すべてのリファレンスのリスト。

entity-reference.[n].name

String (文字列)

参照される種別の名前。API に含まれる場合も含まれない場合もあります。

entity-reference.[n].fieldName

String (文字列)

この種別について作成される新しい項目の名前。

entity-reference.[n].keyMapping

Map (マップ)

マップのキーはこの種別の項目を表しており、値は参照される種別のキーを表しています。

OAS の例

components:
  Schemas:
    Order:
    	x-entity-reference:
        - name: Customer
          fieldName: customer
          keyMapping:
            customerId: id
        - name: Store
          fieldName: store
          keyMapping:
            storeId: id
      properties:
    	  orderItems:
          ...
    	  customerId:
          type: string
    	  storeId:
          type: string
    Customer:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  email:
          type: string
    	  id:
          type: string
    Store:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  id:
          type: string
    	  ...

RAML の例

types:
  Order:
    (dg.entity-reference):
      - name: Customer
        fieldName: customer
        keyMapping:
          customerId: id
      - name: Store
        fieldName: store
        keyMapping:
          storeId: id
    properties:
    	orderItems:
        ...
    	customerId:
        type: string
    	storeId:
        type: string
  Customer:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	email:
        type: string
    	id:
        type: string
    	...
  Store:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	id:
        type: string

エンティティプロバイダー

この拡張機能では、エンドポイントが ID によってエンティティのインスタンスを返すとマークします。 DataGraph では、これは​デフォルトのクエリ方法​です。

この拡張機能は、GET 操作に適用されます。

構造

対象は操作で暗黙的であるため、指定されません。

項目 型 説明

entity-provider

Map (マップ)

エンドポイントがエンティティインスタンスを返すとマークします。

entity-reference.keyMapping

Map (マップ)

マップのキーはこの操作のパラメーターを表しており、値は対象種別のキーを表しています。

OAS の例

Schemas:
    Customer:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  email:
          type: string
    	  1:
          type: string
    	  ...
paths:
  "/customers/{customerId}":
    get:
  	x-entityProvider:
    	  keyMapping:
          customerId: id
  	parameters:
    	  - in: query
          name: summaryView
          default: true
          schema:
          type: boolean
  	...
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
            	$ref: "#/components/schemas/Customer"

RAML の例

types:
  Customer:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	email:
        type: string
    	id:
        type: string
    	…

/customer/{customerId}:
  uriParameters:
    customerId: string
  get:
    (dg.entityProvider):
      keyMapping:
        customerId: id
    responses:
      200:
        application/json:
          body: Customer

HTTP メソッドの上書き

この拡張機能を使用して、POST メソッドを GET メソッドとして扱います。この拡張機能では、POST メソッドを変異ではなくクエリ操作に変換します。

この拡張機能は、操作に適用されます。

構造

対象は操作で暗黙的であるため、指定されません。

項目 型 説明

​http-method-override

Map (マップ)

上書きされる操作をマークします。

​http-method-override.method

String (文字列)

元の操作を上書きするために使用される HTTP メソッド。

OAS の例

paths:
  "/customers":
    post:
  	x-http-method-override:
          method: get
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
                type: array
                items:
                  $ref: "#/components/schemas/Customer"

RAML の例

/customers:
  post:
    (dg.http-method-override):
      method: get
    responses:
      200:
        body:
          application/json:
            type: Customer[]

DataGraph 固有の拡張機能

メインのアノテーション ​datagraph​ を異なるドメインで同じ名前にすることはできません。そのため、操作、種別、オブジェクトプロパティのアノテーションではポストフィックスを使用します。

  • 操作: -method

  • 種別: -type

  • オブジェクトプロパティ: -field

非表示

この拡張機能を使用して、要素を非表示とマークします。非表示の要素は統合スキーマに表示されず、DataGraph ではどのクエリでも非表示の要素が返されません。

この拡張機能は、以下に適用されます。

  • 操作

  • 任意の種別

  • オブジェクトプロパティ

構造

対象は操作で暗黙的であるため、指定されません。

項目 型 説明

​datagraph

Map (マップ)

DataGraph 固有のアノテーションのコンテナ。

​datagraph.hide

Boolean (ブール)

true​ の場合、要素は統合スキーマで非表示になります。​false​ の場合、要素は非表示にならず、アノテーションを設定しなかった場合と同じ結果が得られます。

OAS の例

components:
  Schemas:
    Customer:
  	x-datagraph:
    	  hide: true
  	properties:
    	  name:
          type: string
    	  email:
          type: string
  	    x-datagraph:
    	      hide: true
    	  id:
          type: string
    	  ...
paths:
  "/customers/{customerId}":
    get:
  	x-datagraph:
    	  hide: true
  	parameters:
    	  - in: query
          name: summaryView
          default: true
          schema:
          type: boolean
  	...
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
            	$ref: "#/components/schemas/Customer"

RAML の例

types:
  Customer:
    (dg.datagraph):
      hide: true
    properties:
    	name:
        type: string
    	email:
        type: string
        (dg.datagraph):
          hide: true
    	id:
        type: string
    	…

/customer/{customerId}:
  uriParameters:
    customerId: string
  get:
    (dg.datagraph):
      hide: true
    responses:
      200:
        application/json:
          body: Customer

名前

この拡張機能を使用して、統合スキーマの要素に特定の名前を定義するなど、DataGraph で要素の目的の名前を設定します。この拡張機能を使用して、基礎となる API を変更することなく、さまざまな API の種別を統合できます。

この拡張機能は、以下に適用されます。

  • 操作

  • 任意の種別

  • オブジェクトプロパティ

構造

対象は操作で暗黙的であるため、指定されません。

項目 型 説明

​datagraph

Map (マップ)

DataGraph 固有のアノテーションのコンテナ。

​datagraph.name

String (文字列)

DataGraph の要素の目的の名前。可能であれば、有効な名前にパターンを使用してください。

OAS の例

components:
  Schemas:
    Customer:
  	x-datagraph:
    	  name: SalesCustomer
  	properties:
    	  name:
          type: string
    	  e-mail:
          type: string
  	    x-datagraph:
    	      name: email
    	  id:
          type: string
    	  ...
paths:
  "/customers/{customerId}":
    get:
  	x-datagraph:
    	  name: getCustomer
  	parameters:
    	  - in: query
          name: summaryView
          default: true
          schema:
          type: boolean
  	...
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
            	$ref: "#/components/schemas/Customer"

RAML の例

types:
  Customer:
    (dg.datagraph):
      name: SalesCustomer
    properties:
    	name:
        type: string
    	e-mail:
        type: string
          (dg.datagraph):
            name: email
    	id:
        type: string
    	…

/customer/{customerId}:
  uriParameters:
    customerId: string
  get:
    (dg.datagraph):
      name: getCustomer
    responses:
      200:
        application/json:
          body: Customer

関連情報