1. Homepage
  2. Anypoint Code Builder

  3. API 仕様フラグメントの作成と使用

API 仕様フラグメントの作成と使用

logo cloud IDE Cloud IDE

logo desktop IDE Desktop IDE

これは進行中のベータリリースです。ベータ状態での Anypoint Code Builder の使用には、該当するベータサービス契約条件が適用されます。

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

Anypoint Code Builder は、Exchange からプロジェクトの連動関係としてインポートする OAS または JSON スキーマフラグメントを参照するスキャフォールディング API 仕様をサポートしていません。 代わりに、仕様内でインラインでフラグメントを指定するか、プロジェクトディレクトリ内で手動で作成したフラグメントファイルを通じて、そのようなフラグメントを含む仕様をスキャフォールディングできます。Exchange の RAML フラグメントは、この制限の影響を受けません。

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

  1. API 仕様プロジェクトに連動関係として ​API フラグメントを Exchange から追加します​。

  2. $ref​ (OAS) または ​!include​ (RAML) ディレクティブを使用して、​API フラグメントを API 仕様に追加します​。

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

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

始める前に

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

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

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

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

  1. IDE のアクティビティバーで、​​ (​Anypoint Code Builder​) アイコンをクリックします。

    アクティビティバー内で強調表示されている 「Anypoint Code Builder」 アイコン

  2. [Quick Actions (クイックアクション)]​ から ​[Design an API (API を設計)]​ をクリックします。

    「Quick Actions (クイックアクション)」 セクション内の強調表示された 「Design an API (API を設計)」リンク

  3. [Design an API (API の設計)]​ で、​[API Fragment (API フラグメント)]​ タブをクリックします。

    「Design an API (API の設計)」 ページの 「API Fragment (API フラグメント)」 タブ

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

  4. [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]​ を選択します。

    Business Group (ビジネスグループ)

    API フラグメントの Anypoint Platform のビジネスグループ。 ビジネスグループを参照してください。

    API フラグメントの作成後に、選択したビジネスグループを変更することはできません。

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

    プロンプトが表示されたら、フォルダー内のファイルの作成者を信頼します。

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

    「Design an API (API の設計)」 ページの 「API Fragment (API フラグメント)」 タブ

  6. API フラグメントの設計を続けます。

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

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

  7. Design Center とフラグメントを同期​します。

  8. フラグメントを Exchange にパブリッシュ​します。

    ステータスバーに進行状況が表示されます。 完了すると、API フラグメントが Exchange に正常にパブリッシュされたことを示すメッセージが表示されます。

  9. Anypoint Platform に移動し、ログイン情報を使用してログインします。

    手順を表示

  10. Anypoint Exchange に移動します。

    手順を表示

    API 仕様は、組織内で API 仕様フラグメントタイプのアセットとして表示されます。次に例を示します。

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

  1. API 仕様プロジェクトファイル (​example-oas-spec​ など) を開きます。

  2. コマンドパレットを開きます。

    手順を表示

    • キーボードショートカットを使用する。

      • Mac: Cmd+Shift+p

      • Windows: Ctrl+Shift+p

    • デスクトップ IDE で、​[View (表示)]​ > ​[Command Palette (コマンドパレット)]​ を選択する。

    • クラウド IDE で、​​ (メニュー) アイコンをクリックし、​[View (表示)]​ > ​[Command Palette (コマンドパレット)]​ を選択する。

  3. mulesoft​ と入力し、次のコマンドを選択します。

    MuleSoft: Add Fragment dependency from Exchange

  4. Anypoint Platform にログインするように促されたら、ログインします。

  5. [Search for Asset (アセットの検索)]​ 項目に、追加するデータ型アセットの名前を入力します。

    アセットを検索するには、検索語を入力して Enter キーを押します。次に例を示します。

    Exchange ドロップダウンからアセットのフラグメントを検索

  6. [Assets From Exchange (Exchange からのアセット)]​ メニューからフラグメントを選択します。

  7. フラグメントのバージョンを選択します。

    ステータスバーに進行状況が表示されます。完了すると、選択した API フラグメントがプロジェクトに正常に追加されたことを示すメッセージが表示されます。

  8. exchange.json​ ファイルの ​dependencies​ セクションをチェックして、フラグメントの連動関係が追加されたことを確認します。次に例を示します。

    exchange.json ファイル内のフラグメントの連動関係を確認

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

    エクスプローラービューの API フラグメント

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

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

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

  1. API 仕様プロジェクトファイル (​example-oas-spec​ など) を開きます。

  2. フラグメントを追加する場所にカーソルを置きます。

  3. API 仕様言語に応じて、ディレクティブを選択してフラグメントを仕様に追加します。

    • OAS 仕様: $ref​ ディレクティブを使用します。

    • RAML 仕様: !include​ ディレクティブを使用します。

    • OAS の例

    • RAML の例

    この ​$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

  4. オートコンプリート​ (Ctrl+Space) を使用して、各コンテキスト内で使用可能なオプションを表示します。次に例を示します。

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

  5. フラグメントファイルで定義されたコンポーネント内の要素を参照する手順は、次のとおりです。

    1. フラグメントファイル名を選択します。

    2. 「​#/​」と入力します。

    3. Ctrl+Space を押します。

    4. オプションから要素を選択します。次に例を示します。

      フラグメント内の要素を参照

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

  • 連動関係に移動する。

    フラグメント参照にカーソルを置き、Command キーを押しながらクリックします。 次に例を示します。

    フラグメント連動関係に移動

  • API Console で連動関係を表示する。

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

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

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

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

  1. API 仕様プロジェクトファイル (​example-oas-spec​ など) を開きます。

  2. エクスプローラービューで、空のスペースを右クリックし、​fragments​ などのフラグメント用のフォルダーを作成します。

  3. fragments​ フォルダーで、​my-fragment​ などの新しいファイルを作成し、フラグメントコードを追加します。

  4. フラグメントを追加する場所にカーソルを置きます。

  5. API 仕様言語に応じて、フォルダーからフラグメントを仕様に追加するディレクティブを選択します。

    • OAS 仕様: $ref​ ディレクティブを使用します。

    • RAML 仕様: !include​ ディレクティブを使用します。

    • OAS の例

    • RAML の例

    この ​$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

  6. オートコンプリート​ (Ctrl+Space) を使用して、各コンテキスト内で使用可能なオプションを表示します。次に例を示します。

    フラグメントをフォルダーから API に追加

  7. フラグメントファイルで定義されたコンポーネント内の要素を参照する手順は、次のとおりです。

    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:

関連情報