API 仕様の作成およびインポート

進行中のベータリリース​: クラウド IDE は進行中のベータリリースです。ベータ状態での Anypoint Code Builder の使用には、IDE で入手できる、該当するベータサービス契約条件が適用されます。

Anypoint Exchange にパブリッシュする前に Anypoint Code Builder を使用して API 仕様の作成、インポート、テストを行います。

  1. IDE から Anypoint Code Builder で API 仕様プロジェクトを作成するか、Design Center から仕様をインポートして API 仕様プロジェクトを作成します。

  2. 出力パネルで進行状況を追跡します​。

  3. API Console で仕様を確認します​。

  4. モッキングサービスを使用して仕様をテストします​。

Anypoint Code Builder の機能を調べるには、​oas-example​ API 仕様を使用してください。

始める前に

新しい API 仕様プロジェクトを作成する

Anypoint Code Builder で API 仕様プロジェクトを作成する手順は、次のとおりです。

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

    アクティビティバー内で強調表示されている [Anypoint Code Builder] アイコン
  2. [Quick Actions (クイックアクション)]​ から ​[Design an API (API を設計)]​ をクリックします。

    *「Quick Actions (クイックアクション)」* セクション内の強調表示された *「Design an API (API を設計)」* リンク
  3. [API Specification (API 仕様)]​ フォームに入力します。

    項目名 Field Value (項目値)

    Project Name (プロジェクト名)

    プロジェクトの一意の名前。

    この名前は Exchange での API 仕様のタイトル、仕様ファイルの名前、プロジェクトのルートディレクトリの名前として使用されます。 たとえば、プロジェクト名が​「OAS Example」​ (OAS 例) の場合、仕様ファイル名は ​oas-example​ になります。

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

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

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

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

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

    API Specification Language (API 仕様言語)

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

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

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

    プロジェクトの編集準備が整ったら、API プロジェクトのエディタービューで次の OAS 3.0 (YAML) 仕様のような仕様が開きます。

    新しい OAS 3.0 (YAML) API プロジェクト
  5. 引き続き API 仕様を設計します。

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

Design Center からの API 仕様のインポート

Design Center から API 仕様をインポートします。必要に応じて、Anypoint ソース制御管理 (SCM) システムを使用して、プロジェクトと Design Center との同期を維持します。または、VS Code との互換性がある Git または別の SCM をデスクトップまたはクラウド IDE で使用します。詳細は、​API 設計プロジェクトのソース制御​を参照してください。

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

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

      • Mac: Cmd+Shift+p

      • Windows: Ctrl+Shift+p

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

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

  2. 次のコマンドを入力します。

    MuleSoft: Import API Specification from Design Center
  3. Anypoint Platform にログインするように促されたら、IDE からログインします。

  4. インポートプロセスを完了します。

    1. [Select a Business Group (ビジネスグループを選択)]​ ポップアップからビジネスグループを選択します。

    2. [APIs from Design Center (Design Center から API)]​ 項目で API 仕様を検索します。

    3. 仕様のフォルダーに移動するか、そのフォルダーを作成して、​[Select target folder (対象フォルダーを選択)]​ をクリックします。

      インポートが失敗したといったエラー (​「Importing project a_project_name has failed (プロジェクト a_project_name のインポートに失敗しました)」​) を受け取ったら、同じ名前のプロジェクトの対象フォルダーを確認します。インポートする前に重複する名前の問題に対処するには、設計プロジェクトを別の対象フォルダーにインポートするか、プロジェクトを IDE から削除することができます (API 仕様とフラグメントの削除を参照)。

  5. 必要に応じて、仕様を編集するか、引き続き仕様を設計します。

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

  6. 必要に応じて、Anypoint SCM を使用して変更内容を Design Center と同期します。

    この機能は、Design Center からインポートした API プロジェクトでのみ使用できます。作業内容を別の SCM に保存することもできます。SCM オプションについては、ソースファイルの制御を参照してください。

出力パネルで進行状況を追跡する

API を設計しているときに内部処理の進行状況を追跡する手順は、次のとおりです。

  1. 出力パネルを開きます。

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

      • Mac: Cmd+Shift+u

      • Windows: Ctrl+Shift+u

    • デスクトップ IDE で、​[View (表示)]​ > ​[Output (出力)]​ を選択する。

    • クラウド IDE で、​​ (メニュー) アイコンをクリックし、​[View (表示)]​ > ​[Output (出力)]​ を選択する。

  2. ドロップダウンから ​[Mule DX Server (Mule DX サーバー)]​ を選択します:

    出力ペイン内の [Mule DX Server (Mule DX サーバー)]

API Console で仕様を確認する

コンソールに仕様を表示する手順は、次のとおりです。

  1. エディターで仕様ファイルをクリックします。

  2. ​ (​API Console​) アイコンをクリックします。

    または、​コマンドパレット​でコマンド ​MuleSoft: API Console​ を入力することができます。

  3. API Console にエンドポイントが表示されるまで待機します。

    API Console に仕様のエンドポイントが表示されます。次に例を示します。

    API Console 内の API 仕様
    1 メソッドをクリックして詳細を表示します。
    2 コンソールメニューを表示します。
  4. コンソールでメソッドをクリックするか、メニューから項目を選択して、仕様のさまざまな部分を表示します。 たとえば、​[GET]​ をクリックすると、次のように表示されます。

    Get の詳細を含む API Console

モッキングサービスを使用して API 仕様をテストする

API Console でモッキングサービスを使用して、API 仕様で設定した要求と応答を確認します。

  1. Anypoint Code Builder で API プロジェクトの仕様 (​oas-example​ など) を開きます。

  2. ​ (​API Console​) アイコンをクリックして、コンソールに仕様を表示します。

  3. API Console で GET や POST などのメソッドをクリックします。

  4. [Try It (試す)]​ をクリックします。

    API Console の [Try It (試す)] ボタン
  5. 定義したパラメーターが正しいことを確認して、​[Send (送信)]​ をクリックします。

  6. 定義した応答が API Console に返されることを検証します。次に例を示します。

    API Console での応答例
  7. 必要に応じて、モックされた API エンドポイントを照会するときに、設定済みの応答例を確認します。

OAS 3.0 (YAML) API 仕様の例

OAS 3.0 (YAML) プロジェクトを作成したら、初期仕様を次のコード例で置き換えることができます。

OAS 3.0 (YAML) API 仕様の例
  openapi: "3.0.0"
  info:
    version: 1.0.0
    title: oas-example
  paths:
    /contacts:
      get:
        summary: Retrieve a list of contacts
        description: Returns a list of contacts.
        responses:
          '200':
            description: Successful response
            content:
              application/json:
                example:
                  - id: 1
                    firstName: John
                    lastName: Doe
                    company: Example Corp
                  - id: 2
                    firstName: Jane
                    lastName: Smith
                    company: Another Company

      post:
        summary: Create a new contact
        description: Creates a new contact.
        requestBody:
          description: Contact object to be created
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        responses:
          '201':
            description: Contact created successfully
            content:
              application/json:
                example:
                  id: 3
                  firstName: John
                  lastName: Doe
                  company: Example Corp
          '400':
            description: Invalid request
          '500':
            description: Internal server error

    '/contacts/{contactId}':
      put:
        summary: Update a contact
        description: Updates an existing contact based on the contact ID.
        parameters:
          - name: contactId
            in: path
            description: ID of the contact to update
            required: true
            schema:
              type: integer
              format: int64
        requestBody:
          description: Updated contact object
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        responses:
          '200':
            description: Contact updated successfully
            content:
              application/json:
                example:
                  id: 3
                  firstName: John
                  lastName: Doe
                  company: Updated Corp
          '400':
            description: Invalid request
          '404':
            description: Contact not found
          '500':
            description: Internal server error

  components:
    schemas:
      Contact:
        type: object
        properties:
          id:
            type: integer
            format: int64
          firstName:
            type: string
          lastName:
            type: string
          company:
            type: string
        required:
          - firstName
          - lastName