OAS、RAML、および GraphQL API の実装

API 仕様を作成したら、Anypoint Code Builder を使用して API を実装またはインテグレーションの Mule プロジェクトにスキャフォールディングします。

Anypoint Code Builder は、API 仕様から参照される AsyncAPI、OAS、または JSON スキーマフラグメントファイルのスキャフォールディングをサポートしていません。Exchange から仕様をインポートするときに、スキャフォルダーはこれらのフラグメントをプロジェクトの連動関係として追加しません。ただし、仕様内でインラインで指定されたフラグメントをスキャフォールディングして参照することはできます。Exchange からインポートされた RAML フラグメントは、この制限の影響を受けません。

OAS および JSON スキーマの場合、実装またはインテグレーションプロジェクトディレクトリ内に手動で作成したフラグメントファイルを指定することもできます。

Anypoint Code Builder では、仕様で定義された設定を使用して実装プロジェクト内の基本インターフェースを自動生成します。このインターフェースには、各エンドポイントまたは操作のフロー、XML ベースの組み込みルーター、エラーハンドラーが含まれており、それらをその後 Mule アプリケーション内に実装します。

API を実装するために使用するプロセスは、すでにインテグレーションまたは実装のプロジェクトを作成しているか Exchange に仕様をパブリッシュしているかによって異なります。

Exchange の仕様を使用して API をスキャフォールディングする方法は、次のとおりです。
- 新しいプロジェクトにスキャフォールディングするには、新しいプロジェクトへの API のスキャフォールディングを参照してください。
- 既存のプロジェクトにスキャフォールディングするには、プロジェクトへの API 仕様のインポートを参照してください。
Exchange の仕様への最新の変更でプロジェクトを更新するには、プロジェクトへの API 仕様のスキャフォールディングを参照してください。
仕様を Exchange にパブリッシュせずに API をプロジェクトにスキャフォールディングおよび再スキャフォールディングするには、API の反復的な設計および実装を参照してください。

始める前に

デスクトップまたはクラウド IDE をセットアップしてアクセスします。
API 仕様を作成してテストします。
API 仕様を Exchange にパブリッシュします。
必要に応じて、インテグレーションプロジェクト (Mule アプリケーション) を作成します。

新しいプロジェクトへの API のスキャフォールディング

プロジェクトをまだ作成していない場合は、Anypoint Code Builder を使用して API を新しい Mule プロジェクトにスキャフォールディングします。

IDE のアクティビティバーで、 (Anypoint Code Builder) アイコンをクリックします。
[Quick Actions (クイックアクション)] から [Implement an API (API を実装)] をクリックします。

[Implement an API Specification (API 仕様を実装)] フォームに入力します。

項目名項目値

項目名	項目値
Project Name (プロジェクト名)	プロジェクトの一意の名前。この名前はタイトルおよびプロジェクトファイルの名前として使用されます。たとえば、プロジェクト名が「My Project (私のプロジェクト)」の場合、プロジェクトファイル名は `my-project` になります。
Project Location (プロジェクトの場所)	ホームディレクトリまたは作成する別のディレクトリ。「ホームディレクトリへのフォルダーの追加」を参照してください。別のプロジェクトディレクトリ内にプロジェクトを作成しないでください。
Search an API Specification from Exchange (Exchange から API 仕様を検索)	Exchange の仕様の名前。[Show filters (検索条件を表示)] をアクティブ化して、検索結果を絞り込みます。詳細は、検索結果の絞り込みを参照してください。
Mule Runtime	プロジェクトに使用する Mule Runtime バージョン。
Java Version (Java バージョン)	Mule に使用する Java バージョン。

Project Name (プロジェクト名)

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

この名前はタイトルおよびプロジェクトファイルの名前として使用されます。たとえば、プロジェクト名が「My Project (私のプロジェクト)」の場合、プロジェクトファイル名は my-project になります。

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

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

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

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

Search an API Specification from Exchange (Exchange から API 仕様を検索)

Exchange の仕様の名前。[Show filters (検索条件を表示)] をアクティブ化して、検索結果を絞り込みます。詳細は、検索結果の絞り込みを参照してください。

Mule Runtime

プロジェクトに使用する Mule Runtime バージョン。

Java Version (Java バージョン)

Mule に使用する Java バージョン。

サポートされるバージョンのいずれかを選択できます。IDE は、バージョン設定をプロジェクトの mule-artifact.json ファイルに保存します。作成するプロジェクトのデフォルトの Mule Runtime バージョンと Java バージョンを設定するには、Mule、Java、コネクタのバージョン設定を参照してください。

選択した API 仕様がフォームに表示されます。次に例を示します。

"[Implement an API Specification (API 仕様を実装) フォームで選択された [OAS Example (OAS 例)] API"]

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

プロジェクトを作成すると、Anypoint Code Builder で次の操作が実行されます。
- プロジェクトの pom.xml ファイルに API 仕様を連動関係として追加します。
  <dependency> <groupId>e91cab06-650b-4634-9c6f-5bc4f4fc4d17</groupId> <artifactId>OAS-Example</artifactId> <version>1.0.1</version> <classifier>oas</classifier> <type>zip</type> </dependency>
- Mule と Java のバージョンをプロジェクトの mule-artifact.json ファイルに追加します。
- API を新しい Mule プロジェクトにスキャフォールディングして、設定 XML ファイルを開きます。
  
  設定 XML ファイルには、仕様の各エンドポイントのフロー、エラーハンドラー、組み込みルーターを含む実装プロジェクトのインターフェースが含まれます。次に例を示します。
  
  この例には以下が含まれます。
  メインフロー
  
  組み込みルーターを含む HTTP リスナー
  
  いくつかのエラーハンドラー
  GraphQL API の場合、Anypoint Code Builder では、各 Mule フローのソースとしてデータフェッチャー (<graphql-router:data-fetcher>) も作成されます。データフェッチャーについての詳細は、「GraphQL API の実装 tutorial for an example GraphQL API and データソースへの GraphQL API のマッピング」を参照してください。

Mule アプリケーション内でインターフェースを実装できるようになりました。

プロジェクトへの API 仕様のインポート

インテグレーションプロジェクトを作成している場合、Exchange から API 仕様をインポートすることでインターフェースをプロジェクトにスキャフォールディングできます。この場合、Anypoint Code Builder では、インテグレーションプロジェクトのインターフェース用の個別の設定 XML ファイルが作成されます。

Anypoint Code Builder の [Explorer] ビューで、my-project-name などのインテグレーションプロジェクトを開きます。
コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
次のコマンドを入力します。
```
MuleSoft: Import Asset from Exchange
```
API 仕様の言語に応じて、次のオプションのいずれかを選択します。
- OAS または RAML では Rest API
- GraphQL API
プロンプトが表示されたら、[Allow (許可)] をクリックして、Anypoint Platform を使用したサインインを許可し、ビジネスグループを選択します。
API 仕様の名前を入力して Enter キーを押します。
名前に一致するアセットのリストが IDE に読み込まれるまで待機します。
インポートする API 仕様を選択します。
プロンプトで、API 仕様のバージョン (v1.0.1 など) を選択します。
API 連動関係をスキャフォールディングするように促されたら、[Yes (はい)] を選択します。

API 連動関係をスキャフォールディングすると、Anypoint Code Builder では次の操作が実行されます。
- プロジェクトの pom.xml ファイルに API 仕様を連動関係として追加します。
  <dependency> <groupId>e91cab06-650b-4634-9c6f-5bc4f4fc4d17</groupId> <artifactId>OAS-Example</artifactId> <version>1.0.1</version> <classifier>oas</classifier> <type>zip</type> </dependency>
- Mule と Java のバージョンを mule-artifact.json ファイルに追加します。
  { "minMuleVersion": "4.6.2", "javaSpecificationVersions": [ "11" ] }
- 新しい設定 XML ファイル (oas-example.xml など) をプロジェクトに追加します。
  
  新しい設定 XML ファイルには、仕様の各エンドポイントのフロー、エラーハンドラー、組み込みルーターを含む、インテグレーションプロジェクトのインターフェースが含まれます。次に例を示します。
  
  この例には以下が含まれます。
  - メインフロー
  - 組み込みルーターを含む HTTP リスナー
  - いくつかのエラーハンドラー
    
    GraphQL API の場合、Anypoint Code Builder では、各 Mule フローのソースとしてデータフェッチャー (<graphql-router:data-fetcher>) も作成されます。データフェッチャーについての詳細は、「GraphQL API の実装 tutorial for an example GraphQL API and データソースへの GraphQL API のマッピング」を参照してください。

Mule アプリケーション内でインターフェースを実装できるようになりました。

プロジェクトへの API 仕様のスキャフォールディング

再スキャフォールディングを使用すると、Anypoint Exchange の API 仕様の最新の変更とバージョンで IDE 内のプロジェクトを更新できます。再スキャフォールディングでは、プロジェクトの設定 XML と pom.xml が更新されます。Exchange にパブリッシュされていないローカル API 設計プロジェクトで定義された仕様をスキャフォールディングするには、代わりに API の反復的な設計および実装を参照してください。

この手順は、仕様の最新バージョン (2.0.0 バージョンなど) を Exchange で使用できることを前提とします。

Anypoint Code Builder の [Explorer] ビューで、my-implementation-project などの実装プロジェクトを開きます。
コマンドパレットを開きます。
手順を表示
- キーボードショートカットを使用する。
  
  Mac: Cmd+Shift+p
  
  Windows: Ctrl+Shift+p
- デスクトップ IDE で、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
- クラウド IDE で、 (メニュー) アイコンをクリックし、[View (表示)] > [Command Palette (コマンドパレット)] を選択する。
次のコマンドを入力します。
```
MuleSoft: Import Asset from Exchange
```
API 仕様の言語に応じて、次のオプションのいずれかを選択します。
- OAS または RAML では Rest API
- GraphQL API
プロンプトが表示されたら、[Allow (許可)] をクリックして、Anypoint Platform を使用したサインインを許可し、ビジネスグループを選択します。
API 仕様の名前を入力して Enter キーを押します。
名前に一致するアセットのリストが IDE に読み込まれるまで待機します。
プロンプトで、API 仕様のバージョン (v2.0.0 など) を選択します。
API 連動関係をスキャフォールディングするように促されたら、[Yes (はい)] を選択します。

API 連動関係をスキャフォールディングすると、Anypoint Code Builder では次の操作が実行されます。
- プロジェクトの pom.xml ファイルに API 仕様を連動関係として追加します。
  <dependency> <groupId>e91cab06-650b-4634-9c6f-5bc4f4fc4d17</groupId> <artifactId>phoneSync1005</artifactId> <version>2.0.0</version> <classifier>oas</classifier> <type>zip</type> </dependency>
- プロジェクトのインターフェースが含まれる設定 XML ファイルを、インポートした仕様への変更で更新します。
プロジェクトへの変更があるかどうかを確認します。

たとえば、更新された仕様で新しいエンドポイントが追加される場合、実装プロジェクトの設定 XML にはそのエンドポイントの新しいフローがあります。
仕様で新しいバージョン番号が導入された場合、pom.xml を開き、再スキャフォールディングされた仕様の artifactID の新しい連動関係バージョンを検索します。

インターフェースファイルを調べる

API 仕様をインターフェースにスキャフォールディングしたら、UI キャンバスと設定 XML でインターフェースのスキャフォールディング済みフローとエラーハンドラーを調べます。

[Explorer] ビューで、目的のインターフェースの設定 XML ファイルを開きます。
キャンバス UI が自動的に開かない場合は、アクティビティバーの (Show Mule graphical mode (Mule グラフィカルモードを表示)) アイコンをクリックしてキャンバス UI を開きます。
[Flow List (フローリスト)] をクリックして、フロー間を移動します。

設定 XML で、API 仕様のエンドポイント用に作成したフローを見つけます。

フローの例

    <flow name="oas-example-console">
        <http:listener config-ref="oas-example-httpListenerConfig" path="/console/*">
            <http:response statusCode="#[vars.httpStatus default 200]">
                <http:headers>#[vars.outboundHeaders default {}]</http:headers>
            </http:response>
            <http:error-response statusCode="#[vars.httpStatus default 500]">
                <http:body>#[payload]</http:body>
                <http:headers>#[vars.outboundHeaders default {}]</http:headers>
            </http:error-response>
        </http:listener>
        <apikit:console config-ref="oas-example-config" />
        <error-handler>
            <on-error-propagate type="APIKIT:NOT_FOUND">
                <ee:transform doc:name="Transform Message">
                    <ee:message>
                        <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{message: "Resource not found"}]]></ee:set-payload>
                    </ee:message>
                    <ee:variables>
                        <ee:set-variable variableName="httpStatus">404</ee:set-variable>
                    </ee:variables>
                </ee:transform>
            </on-error-propagate>
        </error-handler>
    </flow>

自動的に生成されたエラーハンドラーコンポーネントを確認します。

エラーハンドラーコンポーネントの例

<apikit:console config-ref="oas-example-config" />
    <error-handler>
        <on-error-propagate type="APIKIT:NOT_FOUND">
            <ee:transform doc:name="Transform Message">
                <ee:message>
                    <ee:set-payload><![CDATA[%dw 2.0
output application/json
---
{message: "Resource not found"}]]></ee:set-payload>
                </ee:message>
                <ee:variables>
                    <ee:set-variable variableName="httpStatus">404</ee:set-variable>
                </ee:variables>
            </ee:transform>
        </on-error-propagate>
    </error-handler>

インターフェースおよび実装ファイルに名前を付ける

API 仕様を既存のインテグレーションにインポートすると、Anypoint Code Builder で設定 XML ファイルの名前が API 仕様名に基づいて自動的に設定されます。ファイル名を、たとえばその機能に基づいてわかりやすい名前に変更することができます。次に例を示します。

interface.xml でアプリケーションへのすべての受信要求を受け取り、スキャフォールディング済みフローで要求を検証してルーティングします。
implementation.xml では、インターフェースへのコールのためのバックエンドロジックを提供します。

ファイルの名前を変更するには、ファイルを右クリックして [Rename (名前変更)] を選択し、新しい名前を指定します。

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan