API 仕様フラグメントの作成および使用

Anypoint Code Builder を使用すると、独自の API フラグメントを作成したり、Anypoint Exchange にパブリッシュして他のユーザーと共有したり、フラグメントを Exchange から API 仕様に追加したり、プロジェクト内にフラグメントを作成して API 仕様に直接追加したりできます。または、Exchange にパブリッシュせずに、プロジェクトにフラグメントを直接作成して追加することもできます。

Anypoint Code Builder では、API 仕様から参照される場合、次のスキーマフラグメントファイルのスキャフォールディングがサポートされています。

	Avro	JSON	RAML
AsyncAPI	はい	はい	いいえ
GraphQL	いいえ	いいえ	はい
OData	いいえ	いいえ	はい
REST	いいえ	いいえ	はい
SOAP	いいえ	いいえ	はい

Avro

JSON

RAML

AsyncAPI

はい

いいえ

GraphQL

いいえ

はい

OData

いいえ

はい

REST

いいえ

はい

SOAP

いいえ

はい

サポートされていないフラグメントを追加した場合、スキャフォールダーは Exchange から仕様をインポートするときに、これらのフラグメントをプロジェクトの連動関係として追加しません。ただし、仕様内でインラインで指定されたスキーマをスキャフォールディングすることはできます。

フラグメントを Exchange から追加するプロセスは次のとおりです。

API 仕様プロジェクトに連動関係として API フラグメントを Exchange から追加します。
$ref (OAS および AsyncAPI) または !include (RAML) ディレクティブを使用して、API フラグメントを API 仕様に追加します。

Exchange にパブリッシュせずにフラグメントを追加するプロセスは次のとおりです。

Exchange にパブリッシュせずに、プロジェクトにフラグメントを直接作成して追加します。

次の例を使用して Anypoint Code Builder の機能を調べます。

example-oas-fragment API 仕様フラグメント
example-oas-api-spec API 仕様
example-asyncapi-avro-fragment AsyncAPI 仕様 Avro スキーマフラグメント
example-asyncapi-spec AsyncAPI 仕様
example-asyncapi-spec-inline-avro AsyncAPI 仕様 (インライン Avro)

始める前に

フラグメントを追加する前に:

Web またはデスクトップ IDE をセットアップしてアクセスします。
API 仕様の設計の基礎を理解します。

詳細は、チュートリアルを参照してください。
ビジネスグループに精通します。

API フラグメントを Anypoint Code Builder から Exchange に追加すると、IDE によりビジネスグループの名前が要求されます。ビジネスグループを参照してください。

API フラグメントを作成して Exchange にパブリッシュする

API 仕様フラグメントを作成およびパブリッシュするプロセスは、API 仕様のプロセスと似ています。

API 仕様フラグメントを作成する手順は、次のとおりです。

IDE のアクティビティバーで、 (Anypoint Code Builder) アイコンをクリックします。
[Quick Actions (クイックアクション)] から [Design an API (API を設計)] をクリックします。
[Design an API (API の設計)] で、[API Fragment (API フラグメント)] タブをクリックします。

ページの [API Fragment (API フラグメント)] タブ"]

必ず [API Fragment (API フラグメント)] タブを選択してください。

[API Fragment (API フラグメント)] フォームに入力します。

項目名項目値

項目名	項目値
Project Name (プロジェクト名)	フラグメントの一意の名前。この名前は、Exchange のフラグメントタイトルおよびフラグメントファイルの名前として使用されます。たとえば、プロジェクト名が「Example OAS Fragment」 (サンプル OAS フラグメント) の場合、仕様ファイル名は `example-oas-fragment` です。既存のプロジェクト名を再利用するには、その名前をすでに使用しているプロジェクトを最初に削除する必要があります。API 仕様とフラグメントの削除を参照してください。
Project Location (プロジェクトの場所)	ホームディレクトリまたは作成する別のディレクトリ。ホームディレクトリへのフォルダーの追加を参照してください。別のプロジェクトディレクトリ内にプロジェクトを作成しないでください。
API Specification Language (API 仕様言語)	「API フラグメントでサポートされる仕様言語」を参照してください。この手順でサンプルを使用するには、[OAS 3.0 (YAML)] を選択します。
<Language> Syntax (<Language> 構文)	選択した言語の構文。この手順でサンプルを使用するには、[YAML] を選択します。

Project Name (プロジェクト名)

フラグメントの一意の名前。

この名前は、Exchange のフラグメントタイトルおよびフラグメントファイルの名前として使用されます。たとえば、プロジェクト名が「Example OAS Fragment」 (サンプル OAS フラグメント) の場合、仕様ファイル名は example-oas-fragment です。

既存のプロジェクト名を再利用するには、その名前をすでに使用しているプロジェクトを最初に削除する必要があります。API 仕様とフラグメントの削除を参照してください。

Project Location (プロジェクトの場所)

ホームディレクトリまたは作成する別のディレクトリ。

ホームディレクトリへのフォルダーの追加を参照してください。

別のプロジェクトディレクトリ内にプロジェクトを作成しないでください。

API Specification Language (API 仕様言語)

「API フラグメントでサポートされる仕様言語」を参照してください。

この手順でサンプルを使用するには、[OAS 3.0 (YAML)] を選択します。

<Language> Syntax (<Language> 構文)

選択した言語の構文。

この手順でサンプルを使用するには、[YAML] を選択します。

[Create Project (プロジェクトを作成)] をクリックします。

確認を促されたら、フォルダー内のファイルの作成者を信頼します。

プロジェクトを編集する準備ができたら、API フラグメントプロジェクトがエクスプローラービューで開きます。たとえば、この OAS 3.0 (YAML) API フラグメントは次のようになります。

ページの [API Fragment (API フラグメント)] タブ"]
API フラグメントの設計を続けます。

要素を入力するときに、オートコンプリート (または Ctrl+Space) を使用すると、コンテキスト内で使用可能なオプションが表示されます。

OAS 3.0 (YAML) フラグメントプロジェクトを作成した場合は、最初の API フラグメントをサンプルコードに置き換えて、仕様へのフラグメントの追加をテストできます。
フラグメントを Exchange にパブリッシュします。

ステータスバーに進行状況が表示されます。完了すると、API フラグメントが Exchange に正常にパブリッシュされたことを示すメッセージが表示されます。
Anypoint Platform に移動し、ログイン情報を使用してログインします。
手順を表示
US クラウド (非 EU ホスト): Anypoint Platform (US)

EU クラウド (EU ホスト): Anypoint Platform (EU)
Anypoint Exchange に移動します。
手順を表示
US クラウド (非 EU ホスト): Exchange (US)

EU クラウド (EU ホスト): Exchange (EU)
API 仕様は、組織内で API 仕様フラグメントタイプのアセットとして表示されます。次に例を示します。
API 仕様が API 仕様フラグメントではなく REST API として Exchange に表示される場合は、IDE のプロジェクトフォルダーにある exchange.json ファイルの classifier 属性が言語に応じて次のいずれかに設定されていることを確認します。
- OAS: oas-components
- RAML: raml-fragment
- JSON スキーマ: json-schema
属性が次のいずれかに設定されている場合、プロジェクトはフラグメントではなく API 仕様になります。
- OAS: oas
- RAML: raml

フラグメントを Exchange からプロジェクトに追加する

API 仕様フラグメントを Exchange からプロジェクトディレクトリに追加して、そのフラグメントを仕様に含めることができるようにする手順は、次のとおりです。

API 仕様プロジェクトファイル (example-oas-spec など) を開きます。
コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
mulesoft と入力し、次のコマンドを選択します。
```
MuleSoft: Add Fragment dependency from Exchange
```
Anypoint Platform にログインするように促されたら、ログインします。
[Search for Asset (アセットの検索)] 項目に、追加するデータ型アセットの名前を入力します。

アセットを検索するには、検索語を入力して Enter キーを押します。次に例を示します。
[Assets From Exchange (Exchange からのアセット)] メニューからフラグメントを選択します。
フラグメントのバージョンを選択します。

ステータスバーに進行状況が表示されます。完了すると、選択した API フラグメントがプロジェクトに正常に追加されたことを示すメッセージが表示されます。
exchange.json ファイルの dependencies セクションをチェックして、フラグメントの連動関係が追加されたことを確認します。次に例を示します。

また、エクスプローラービューの [Project Dependencies (プロジェクトの連動関係)] の下でフラグメントを確認することもできます。次に例を示します。

フラグメントファイルは、システムのホームディレクトリの .exchange_modules ディレクトリにあります (例: ~/.exchange_modules (Mac))。

API 仕様に API フラグメントを追加する

仕様に API 仕様フラグメントを追加する手順は、次のとおりです。

API 仕様プロジェクトファイル (example-oas-spec など) を開きます。
フラグメントを追加する場所にカーソルを置きます。
API 仕様言語に応じて、ディレクティブを選択してフラグメントを仕様に追加します。
- OAS および AsyncAPI 仕様: $ref ディレクティブを使用します。
- RAML 仕様: !include ディレクティブを使用します。
- OAS の例
- RAML の例
- AsyncAPI の例
この $ref ディレクティブは、example-oas-fragment の AmericanFlightDataType をデータ型として追加します。
schema: $ref: exchange_modules/e91cab06-650b-4634-9c6f-5bc4f4fc4d17/example-oas-fragment/1.0.0/example-oas-fragment.yaml#/components/schemas/AmericanFlightDataType
この !include ディレクティブは、AmericanFlightDataType.raml の AmericanFlight オブジェクトをデータ型として追加します。
types: AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml
この $ref ディレクティブは、example-asyncapi-fragment の AmericanFlightDataType をデータ型として追加します。
payload: $ref: exchange_modules/e91cab06-650b-4634-9c6f-5bc4f4fc4d17/example-asyncapi-fragment/1.0.0/example-asyncapi-fragment.json#/components/schemas/AmericanFlightDataType
オートコンプリート (または Ctrl+Space) を使用して、各コンテキスト内で使用可能なオプションを表示します。次に例を示します。
フラグメントファイルで定義されたコンポーネント内の要素を参照する手順は、次のとおりです。
1. フラグメントファイル名を選択します。
2. 「#/」と入力します。
3. Ctrl+Space を押します。
4. オプションから要素を選択します。次に例を示します。

フラグメントを仕様に追加すると、次の操作を実行できます。

連動関係に移動する。

フラグメント参照にカーソルを置き、Command キーを押しながらクリックします。次に例を示します。
API Console で連動関係を表示する。

フラグメント参照にカーソルを置き、 (API Console) アイコンをクリックして、コンソールでフラグメントを開きます。

詳細は、「API Console で仕様を確認」を参照してください。

仕様内にフラグメントを直接作成して追加する

プロジェクト内にフラグメントを作成して仕様に含める手順は、次のとおりです。

API 仕様プロジェクトファイル (example-oas-spec など) を開きます。
エクスプローラービューで、空のスペースを右クリックし、fragments などのフラグメント用のフォルダーを作成します。
fragments フォルダーで、my-fragment などの新しいファイルを作成し、フラグメントコードを追加します。
フラグメントを追加する場所にカーソルを置きます。
API 仕様言語に応じて、フォルダーからフラグメントを仕様に追加するディレクティブを選択します。
- OAS および AsyncAPI 仕様: $ref ディレクティブを使用します。
- RAML 仕様: !include ディレクティブを使用します。
- OAS の例
- RAML の例
- AsyncAPI の例
この $ref ディレクティブは、my-fragment.yaml ファイルから api_key オブジェクトを追加します。
api-key: $ref: fragments/my-fragment.yaml#/components/securitySchemes/api_key
この !include ディレクティブは、AmericanFlightsExample.raml サンプルを追加します。
examples: output: !include examples/AmericanFlightExample.raml
この $ref ディレクティブは、fragments/my-fragment サンプルを追加します。
payload: $ref: fragments/my-fragment
オートコンプリート (または Ctrl+Space) を使用して、各コンテキスト内で使用可能なオプションを表示します。次に例を示します。
フラグメントファイルで定義されたコンポーネント内の要素を参照する手順は、次のとおりです。
1. フラグメントファイル名を選択します。
2. 「#/」と入力します。
3. Ctrl+Space を押します。
4. オプションから要素を選択します。次に例を示します。

フラグメントを仕様に追加すると、次の操作を実行できます。

連動関係に移動する。

フラグメント参照にカーソルを置き、Command キーを押しながらクリックします。次に例を示します。
API Console で連動関係を表示する。

フラグメント参照にカーソルを置き、 (API Console) アイコンをクリックして、コンソールでフラグメントを開きます。

詳細は、「API Console で仕様を確認」を参照してください。

サンプル OAS 3.0 (YAML) API 仕様フラグメント

OAS 3.0 (YAML) フラグメントプロジェクトを作成した場合は、最初の API フラグメントを次のサンプルコードに置き換えることができます。

サンプル OAS 3.0 (YAML) API 仕様フラグメント

openapi: "3.0.0"
info:
  version: 1.0.0
  title: ExampleComponents
paths: {}

components:
  schemas:
    AmericanFlightDataType:
      type: object
      description: American Flight Data Type
      properties:
        ID:
          type: number
        code:
          type: string
        price:
          type: number
        departureDate:
          type: string
        origin:
          type: string
        destination:
          type: string
        emptySeats:
          type: number
        plane:
          type: object
          properties:
            type:
              type: string
            totalSeats:
              type: number
      example:
        ID: 1
        code: ER38sd
        price: 400
        departureDate: 2017/07/26
        origin: CLE
        destination: SFO
        emptySeats: 0
        plane:
          type: Boeing 737
          totalSeats: 150

サンプル OAS 3.0 (YAML) API 仕様

OAS 3.0 (YAML) API 仕様プロジェクトを作成した場合は、最初の API 仕様を次のサンプルコードに置き換えて、API 仕様フラグメントの追加をテストできます。

サンプル OAS 3.0 (YAML) API 仕様

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Example OAS Spec
paths:

  /flights/{ID}:
    get:
      parameters:
        -
          name: ID
          required: true
          in: path
          schema:
            type: string
      responses:
        "200":
          description: "Flight with ID"
          content:
            application/json:
              schema:

サンプル AsyncAPI 仕様 Avro スキーマフラグメント

Avro スキーマフラグメントを作成した場合は、最初の API フラグメントを次のサンプルコードに置き換えることができます。

サンプル AsyncAPI 仕様 Avro スキーマフラグメント

{
  "name": "AmericanFlightDataType",
  "type": "record",
  "fields": [
    {"name": "ID", "type": "int", "example": 1},
    {"name": "code", "type": "string", "example": "ER38sd"},
    {"name": "price", "type": "int", "example": 400},
    {"name": "departureDate", "type": "string", "example": "2017/07/26"},
    {"name": "origin", "type": "string", "example": "CLE"},
    {"name": "destination", "type": "string", "example": "SFO"},
    {"name": "emptySeats", "type": "int", "example": 0},
    {
      "name": "plane",
      "type": {
        "name": "Plane",
        "type": "record",
        "fields": [
          {"name": "type", "type": "string"},
          {"name": "totalSeats", "type": "int"}
        ]
      }
    }
  ]
}

サンプル AsyncAPI 仕様

AsyncAPI 仕様プロジェクトを作成した場合は、最初の API 仕様を次のサンプルコードに置き換えて、API 仕様フラグメントの追加をテストできます。

サンプル AsyncAPI 仕様

asyncapi: 2.6.0
info:
  title: Example AsyncAPI Spec
  version: '1.0.0'
channels:
  myChannel:
    publish:
      message:
        schemaFormat: application/vnd.apache.avro;version=1.9.0
        payload:
          $ref: exchange_modules/e91cab06-650b-4634-9c6f-5bc4f4fc4d17/example-asyncapi-fragment/1.0.0/example-asyncapi-fragment.json

サンプル AsyncAPI 仕様 (インライン Avro)

AsyncAPI 仕様プロジェクトを作成した場合は、最初の API 仕様を次のサンプルコードに置き換えて、API 仕様フラグメントのインラインをテストできます。

サンプル AsyncAPI 仕様 (インライン Avro)

asyncapi: 2.6.0
info:
  title: Example AsyncAPI Spec (Inline Avro)
  version: '1.0.0'
channels:
  myChannel:
    publish:
      message:
        schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
        payload:
          name: AmericanFlightDataType
          type: record
          fields:
            - name: ID
              type: int
              example: 1
            - name: code
              type: string
              example: ER38sd
            - name: price
              type: int
              example: 400
            - name: departureDate
              type: string
              example: 2017/07/26
            - name: origin
              type: string
              example: CLE
            - name: destination
              type: string
              example: SFO
            - name: emptySeats
              type: int
              example: 0
            - name: plane
              type:
                name: Plane
                type: record
                fields:
                  - name: type
                    type: string
                  - name: totalSeats
                    type: int

API 仕様フラグメントの作成および使用

始める前に

API フラグメントを作成して Exchange にパブリッシュする

フラグメントを Exchange からプロジェクトに追加する

API 仕様に API フラグメントを追加する

仕様内にフラグメントを直接作成して追加する

サンプル OAS 3.0 (YAML) API 仕様フラグメント

サンプル OAS 3.0 (YAML) API 仕様

サンプル AsyncAPI 仕様 Avro スキーマフラグメント

サンプル AsyncAPI 仕様

サンプル AsyncAPI 仕様 (インライン Avro)

関連情報