API 仕様の反復的な設計と実装

logo desktop IDE Desktop IDE

REST API 仕様を IDE 内の実装プロジェクトにスキャフォールディングして、仕様への変更を最初に Anypoint Exchange にパブリッシュすることなくインターフェースと同期します。たとえば、新しいエンドポイントを API 仕様に追加したら、その変更をインターフェースに再スキャフォールディングして、そのエンドポイントのフローをインターフェースの設定 XML ファイルに追加できます。

インターフェース XML は、スキャフォールディングプロセス中に Mule プロジェクトに自動的に作成されます。API を API 設計プロジェクト内の仕様ファイルで定義します。

IDE 内での反復的な API 設計と実装は、VS Code のマルチルートワークスペースで実行されます。API 仕様および実装プロジェクトのプロジェクトフォルダーをマルチルートワークスペースにマッピングするため、VS Code では拡張子 .code-workspace 付きのファイルが使用されます。プロジェクトを適切に動作させるには、このファイルはどちらのプロジェクトフォルダーにも存在してはなりません。また、Anypoint Code Builder では、反復的な設計フォルダーと実装プロジェクトフォルダーのペアがマルチルートワークスペースごとに 1 つのみ許可されます。仕様および実装プロジェクトを作成するための手順は次の要件を満たすように設計されています。VS Code ドキュメントで情報を確認するには、「Multi-root Workspaces (マルチルートワークスペース)」 Leaving the Site を参照してください。

現在、この手順はデスクトップ IDE のみを対象として記載されています。

始める前に

MuleSoft 環境をセットアップします。詳細は、『Anypoint Code Builder 入門』を参照してください。
『ビジネスグループ』に精通します。

API 仕様を Anypoint Code Builder から Exchange にパブリッシュすると、IDE でビジネスグループの名前が要求されます。『ビジネスグループ』を参照してください。

API 仕様を作成する

デスクトップ IDE で Cmd+Shift+n (Mac) または Ctrl+Shift+n (Windows) を押して、VS Code で新しいウィンドウを開きます。

このステップにより、反復的な設計および実装プロジェクトがすでに含まれているマルチルートワークスペースに API 仕様を作成できなくなり、次の手順 (ローカル REST API 仕様をインターフェースにスキャフォールディングする) で必要なコマンドが使用できるようになります。
デスクトップ IDE のアクティビティバーで ([Anypoint Code Builder]) アイコンをクリックして Anypoint Code Builder を開きます。
クイックアクション [Design an API (API を設計)] をクリックして、API 仕様を開始します。

または、Ctrl+Shift+p (Mac) または Cmd+Shift+p (Windows) を押してコマンドパレットを開き、次のコマンドを入力します。
```
MuleSoft: Design an APIcommand
```
Anypoint Platform にサインインするように促されたら、サインインし、すべてのプロンプトに従って IDE を再開します。

[API Specification (API 仕様)] フォームに入力します。

項目名	項目値
Project Name (プロジェクト名)	Retrieve Users API (ユーザーの取得 API) または、任意の同様の名前を指定します。名前は一意である必要があります。プロジェクトと仕様ファイルの名前は、指定した名前に基づきます。
Project Location (プロジェクトの場所)	ホームディレクトリまたは作成する別のディレクトリ (『ホームディレクトリへのフォルダーの追加』を参照)。
API Type (API 種別)	REST API Anypoint Code Builder では、反復的な設計に REST API 種別がサポートされます。
API Specification Language (API 仕様言語)	RAML 1.0 Anypoint Code Builder では、OAS (JSON)、OAS (YAML)、および RAML がサポートされます。

項目名

項目値

Project Name (プロジェクト名)

Retrieve Users API (ユーザーの取得 API)
または、任意の同様の名前を指定します。名前は一意である必要があります。プロジェクトと仕様ファイルの名前は、指定した名前に基づきます。

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

ホームディレクトリまたは作成する別のディレクトリ (『ホームディレクトリへのフォルダーの追加』を参照)。

API Type (API 種別)

REST API
Anypoint Code Builder では、反復的な設計に REST API 種別がサポートされます。

API Specification Language (API 仕様言語)

RAML 1.0
Anypoint Code Builder では、OAS (JSON)、OAS (YAML)、および RAML がサポートされます。

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

このプロセスでは、API 仕様を含むプロジェクトがワークスペース内に作成されます。
API 仕様ファイル (retrieve-users-api.raml) を開きます。
内部プロセスの進行状況を追跡するには、[Mule DX Server (Mule DX サーバー)] への [Output (出力)] パネルを開きます。
手順を表示
Cmd+Shift+u (Mac) または Ctrl+Shift+u (Windows) を押して [Output (出力)] パネルを開きます。

パネルのドロップダウンメニューから [Mule DX Server] を選択します。

詳細は、『出力パネルを開く』を参照してください。

API 仕様のエディターで次の例を retrieve-users-api.raml に追加します。

#%RAML 1.0
title: Retrieve Users API
version: 1.0.development
/users:
  get:
    description: Retrieve a list of all the users
    responses:
      200:
        body:
          application/json:
            example: |
              [{
              "id": 1,
              "name": "Leanne Graham",
              "username": "Bret",
              "email": "Sincere@april.biz",
              "address": {
                "street": "Kulas Light",
                "suite": "Apt. 556",
                "city": "Gwenborough",
                "zipcode": "92998-3874",
                "geo": {
                  "lat": "-37.3159",
                  "lng": "81.1496"
                }
              },
              "phone": "1-770-736-8031 x56442",
              "website": "hildegard.org",
              "company": {
                "name": "Romaguera-Crona",
                "catchPhrase": "Multi-layered client-server neural-net",
                "bs": "harness real-time e-markets"
              } }]raml
コンテンツを展開する

ローカル REST API 仕様をインターフェースにスキャフォールディングするに進みます。

ローカル REST API 仕様をインターフェースにスキャフォールディングする

ローカル REST API 仕様をローカル実装プロジェクトにスキャフォールディングします。スキャフォールディングプロセスにより実装の設定 XML が作成されます。

プロジェクトがデスクトップ IDE にあるか Anypoint Platform 内のユーザーアカウントに関連付けられたクラウド IDE にあるかにかかわらず、ローカルプロジェクトは Anypoint Code Builder IDE に存在します。

ローカル API 仕様をスキャフォールディングする手順は、次のとおりです。

IDE で retrieve-users-api.raml を開いて、仕様を Mule プロジェクトにスキャフォールディングする準備を整えます。

アクティビティバーで ([Implement this local API (このローカル API を実装)]) アイコンをクリックします。

または、Cmd+Shift+p (Mac) または Ctrl+Shift+p (Windows) を押してコマンドパレットを開き、次のコマンドを入力します。
```
MuleSoft: Implement this Local APIcommand
```
コマンド [MuleSoft: Implement an API Specification (Mulesoft: API 仕様を実装する)] を選択しないでください。これは、Anypoint Exchange にパブリッシュする仕様を実装するコマンドであり、ローカル API 仕様を実装するコマンドではありません。

UI にメッセージ [We’ll create a workspace to keep your API specification and Mule project in sync (API 仕様と Mule プロジェクトの同期を維持するためのワークスペースを作成します)] が表示されたら [OK] をクリックします。

マルチワークスペースの拡張子 .code-workspace 付きのファイルを保存するように促すプロンプトで、このファイルを API 仕様プロジェクトフォルダー内に保存しないでください。代わりに、次のステップに進みます。

ワークスペース用に作成した親フォルダーまで移動して .code-workspace ファイルを保存します。
[Output (出力)] パネルで [Mule DX Server (Mule DX サーバー)] 出力を使用して内部プロセスの進行状況を追跡できることを確認します。

UI にメッセージ [Implementing local API implementation, please wait. (ローカル API 仕様を実装しています。お待ちください。)] が表示されます。

出力を監視しながら、プレースホルダーテキスト [Mule project name (Mule プロジェクト名)] を含む項目が UI に表示されるまで待ちます。次に例を示します。

Mule 実装プロジェクトの名前 (retrieve-users-implementation など) を入力して、スキャフォールディングプロセスを開始します。
確認を促されたら、[Select target folder (対象フォルダーを選択)] をクリックします。

対象フォルダーは、API 仕様が作成されたプロジェクトフォルダーです。

スキャフォールディングプロセスが実行されている間、UI で更新情報が提供されます。
- Executing scaffolding operation, please wait (スキャフォールディング操作を実行しています。お待ちください)
- Scaffolding process ended. You can now start iterating over your local API and implementation project (スキャフォールディングプロセスが終了しました。ローカル API および実装プロジェクトの反復を開始できるようになりました)

[Explorer] のマルチルートワークスペースから、新しい Mule プロジェクトでスキャフォールディング済み仕様が開きます。

実装用の設定 XML ファイル (retrieve-users-implementation.xml) は、次のような実装プロジェクトディレクトリに配置されています。

retrieve-users-implementation/src/main/mule/retrieve-users-implementation.xmlimplementation project directory

この Mule プロジェクトのキャンバスには Router コンポーネントといくつかのエラーハンドラーが含まれます。APIkit によりこれらのコンポーネントはスキャフォールディングプロセス中に自動的に作成されます。

実装 XML のフロー <flow name="get:\users:retrieve-users-api-config"> には、例を含む <ee:transform/> 要素が含まれます。

<flow name="get:\users:retrieve-users-api-config">
    <ee:transform doc:name="Transform Message">
        <ee:message>
            <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
[
{
id: 1,
name: "Leanne Graham",
username: "Bret",
email: "Sincere@april.biz",
address: {
  street: "Kulas Light",
  suite: "Apt. 556",
  city: "Gwenborough",
  zipcode: "92998-3874",
  geo: {
    lat: "-37.3159",
    lng: "81.1496"
  }
},
phone: "1-770-736-8031 x56442",
website: "hildegard.org",
company: {
  name: "Romaguera-Crona",
  catchPhrase: "Multi-layered client-server neural-net",
  bs: "harness real-time e-markets"
}
}
]]]></ee:set-payload>
        </ee:message>
    </ee:transform>
</flow>XML
コンテンツを展開する

API 仕様を更新して実装 XML を再スキャフォールディングするに進みます。

API 仕様を更新して実装 XML を再スキャフォールディングする

エンドポイントを仕様ファイルに追加して、再スキャフォールディングします。

[Explorer] で [Retrieve Users API (ユーザーの取得 API)] ディレクトリの仕様ファイル retrieve-users-api.raml に移動します。

次の /userbyid エンドポイント設定を RAML ファイルに追加します。

#%RAML 1.0
title: Retrieve User
version: 1.0.development
/users:
  get:
    description: Retrieve a list of all the users
    responses:
      200:
        body:
          application/json:
            example: |
              [{
              "id": 1,
              "name": "Leanne Graham",
              "username": "Bret",
              "email": "Sincere@april.biz",
              "address": {
                "street": "Kulas Light",
                "suite": "Apt. 556",
                "city": "Gwenborough",
                "zipcode": "92998-3874",
                "geo": {
                  "lat": "-37.3159",
                  "lng": "81.1496"
                }
              },
              "phone": "1-770-736-8031 x56442",
              "website": "hildegard.org",
              "company": {
                "name": "Romaguera-Crona",
                "catchPhrase": "Multi-layered client-server neural-net",
                "bs": "harness real-time e-markets"
              } }]
  /userbyid:
    get:
      description: Get information about a particular user
      queryParameters:
        id:
          description: Specify the id of the user you want to retrieve
          type:        integer
          required:    false
          example: 3
      responses:
        200:
          body:
            application/json:
              example: |
                [{
                "id": 3,
                "name": "Clementine Bauch",
                "username": "Samantha",
                "email": "Nathan@yesenia.net",
                "address": {
                  "street": "Douglas Extension",
                  "suite": "Suite 847",
                  "city": "McKenziehaven",
                  "zipcode": "59590-4157",
                  "geo": {
                    "lat": "-68.6102",
                    "lng": "-47.0653"
                  }
                },
                "phone": "1-463-123-4447",
                "website": "ramiro.info",
                "company": {
                  "name": "Romaguera-Jacobson",
                  "catchPhrase": "Face to face bifurcated interface",
                  "bs": "e-enable strategic applications"
                } }]raml
コンテンツを展開する

API 仕様を再スキャフォールディングして Mule プロジェクトを更新します。

Cmd+Shift+p (Mac) または Ctrl+Shift+p (Windows) を押してコマンドパレットを開き、次のコマンドを入力します。
```
MuleSoft: Re-scaffold this local APIcommand
```

プロジェクトが正常にスキャフォールディングされたことを示すメッセージを受け取ったら、実装 XML ファイルに移動して、userbyid エンドポイントの新しいフロー (<flow name="get:\users\userbyid:design-an-api-config"/>) を確認します。

...

<flow name="get:\users\userbyid:retrieve-users-api-config">
    <ee:transform doc:name="Transform Message">
        <ee:message>
            <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
[
{
id: 3,
name: "Clementine Bauch",
username: "Samantha",
email: "Nathan@yesenia.net",
address: {
  street: "Douglas Extension",
  suite: "Suite 847",
  city: "McKenziehaven",
  zipcode: "59590-4157",
  geo: {
    lat: "-68.6102",
    lng: "-47.0653"
  }
},
phone: "1-463-123-4447",
website: "ramiro.info",
company: {
  name: "Romaguera-Jacobson",
  catchPhrase: "Face to face bifurcated interface",
  bs: "e-enable strategic applications"
}
}
]]]></ee:set-payload>
        </ee:message>
    </ee:transform>
</flow>XML
コンテンツを展開する

API 仕様を Exchange にパブリッシュするに進みます。

API 仕様を Exchange にパブリッシュする

API 仕様を Anypoint Exchange にパブリッシュして、チームメンバーがその仕様を見つけることができるようにします。

コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。

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

MuleSoft: Publish API Specification to Exchangecommand

確認を促されたら、[Allow (許可)] をクリックし、プロンプトに従って Anypoint Platform にサインインします。
[Select a Business Group (ビジネスグループを選択)] で、プロジェクトのビジネスグループを見つけて選択します。

詳細は、始める前にを参照してください。
プロジェクト名を入力します: Retrieve Users API (ユーザーの取得 API)。
アーティファクト ID を確認します: Retrieve-Users-API。
アセットバージョンを確認します: 1.0.0。
API バージョンを確認します: v1。

API 仕様の v1.0.0 を参照するように Mule プロジェクトの POM ファイルが IDE で更新されるまで、ステータスバーに進行状況関連のメッセージが表示されます。
- Publishing API Specification to Exchange (API 仕様を Exchange にパブリッシュしています)
- Project has been successfully published to Exchange (プロジェクトが Exchange に正常にパブリッシュされました)

ビジネスグループのチームメンバーはこの仕様を Anypoint Exchange Leaving the Site で入手してプロジェクトと実装にスキャフォールディングできるようになりました。API 仕様を Exchange からスキャフォールディングするを参照してください。

API 仕様を Exchange からスキャフォールディングする

ビジネスグループのチームメンバーは API 仕様を Exchange からインポートできます。

新しい VS Code インスタンスを開きます。
API のバージョン 1.0.0 を MuleSoft VCS からインポートします。
1. コマンドパレットを開きます。
  手順を表示
  キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
  
  デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
  
  クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
2. 次のコマンドを入力します。
  MuleSoft: Implement an API Specification (MuleSoft: API 仕様を実装する)
  command
3. 開いている [Implement an API Specification (API 仕様を実装する)] タブで次の操作を実行します。
  - 実装の新しい名前を入力します。
  - 新しいプロジェクトの場所を選択または作成します。
  - Anypoint Exchange で API 仕様を見つけて [Add (追加)] をクリックし、API 参照名を項目に挿入します。
4. [Create Project (プロジェクトを作成)] をクリックして、新しい実装への仕様のスキャフォールディングを開始します。
スキャフォールディング済み仕様を IDE に実装します。

マルチルートワークスペースを閉じる

コマンド [Workspaces: Close Workspace (ワークスペース: ワークスペースを閉じる)] を使用してマルチルートワークスペースを作成します。

閉じた後、同期されたプロジェクトを、API の実装時に作成したワークスペースから再度開くことができます。

マルチルートワークスペースを開く

ワークスペースのプロジェクトの .code-workspace ファイル (Retrieve Users API.code-workspace など) からマルチルートワークスペースを開きます。

VS Code を開きます。
コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。

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

File: Open Workspace from File...command

ワークスペースのプロジェクトの .code-workspace ファイルに移動してダブルクリックします。

[Explorer] ビューでプロジェクトが開きます。マルチルートワークスペースの見出しには [(WORKSPACE)] 識別子が追加されます。次に例を示します。