はじめに

APIを作成する際、通常は
1. API仕様を作成
2. API仕様をAnypointStudioに取り込む
3. AnypointStudioでAPIを実装する

という流れでAPIを作っていきます。
なので前回の記事では、いきなり

3. AnypointStudioでAPIを実装する

をやっていたことになります。
今回は上記の

1. API仕様を作成
2. API仕様をAnypointStudioに取り込む

の部分をやっていこうと思います。

API仕様の記法の選択

MulesoftではAPI仕様の作成において

RAML
OpenAPI

の２つの記法が可能です。
Mulesoftの公式ドキュメントではRAMLがメインな感じでに記載されていますが、
本記事では利用者の多いと思われるOpenAPIでやっていきます。

API仕様の作成

AnypointPlatform上にある、DesignCenterを使って作成します。

DesignCenterにアクセスする

AnypointPlatformにログイン後、[Start designing]をクリック

[+Create new] -> [New API Specificatoin]をクリック

API仕様の記法の選択

API名の設定：今回は hello-muleと名付けました
API機能の選択：今回は OAS3.0(YAML) を選択しました
※OAS：OpenAPI Specificationの略

API仕様を記述する画面の構成

画面の構成を見ていきます。

エクスプローラ
画面左側はAPI仕様のファイルが表示されています。
[+]ボタンからフォルダやファイルを追加することができます。

仕様の記述部分
画面中央にAPI仕様を記述していきます。

入力支援機能
仕様の記述部分の下には、
現在のカーソル位置に合わせて入力可能なキーワードが表示されます。
下図ではtitle: hello-muleから改行した位置にカーソルを当てた際に
入力候補が表示されている状態を載せています。

プレビュー
画面右側は記述中のAPI仕様のプレビューがリアルタイムで反映されます。

API仕様の記述

OpaneAPIの仕様

初期状態は

openapi: "3.0.0"
info:
  version: 1.0.0
  title: hello-mule
paths: {}

となっています。
今回のAPIの仕様は以下のようなものにします。

HTTPメソッド：GET
APIのパス：/hoge
リクエストパラメータ：なし
レスポンス形式：json
- hello:xxx

openapi: "3.0.0"
info:
  version: 1.0.0
  title: hello-mule
paths:
  /hoge:
    get:
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  hello:
                    type: string
              example: 
                hello: "mule!"

API仕様のモックを動かしてみる

ここまで書くと、画面右側のプレビューからAPIモックで動作確認することができます（すごい）。

[GET]をクリック

[Try it]をクリック

記述したAPIエンドポイント/hogeの仕様が確認できます。
右上の[Try it]をクリックします。

[Send]をクリック

ヘッダやリクエストパラメータがあればここで設定できます。

レスポンスを確認

[Send]ボタンの下に結果が表示されました。

あくまでモックなので、
リクエストパラメータ等による動的な結果は得られません。
ここで得られる結果は

              example: 
                hello: "mule!"

の固定した内容です。

APIをPublishする

API仕様の記述が完了したらPublishします。
Publishすることで、API仕様がExchangeに公開され、
AnypointPlatformを利用している他のメンバも仕様を見ることができるようになります。

また、今回の目的である
AnypointStudioでのAPI仕様を取り込んだAPI実装が可能になります。

[Publish] -> [Publish to Exchaange]をクリック

Publishの実行

バージョンを入力して[Publish to Exchange]をクリック

Publish中

Publish完了

PublishしたAPIをExchangeで確認する

Exchangeに移動

AnypointPlatformのトップページからも行けます。

Exchange上でもモック動作確認が可能

Exchange上ででAPI仕様が公開出来ていることを確認できました。
ExchangeでもDesignCenterと同様、モックを動かすことができます。

AnypointStudioでAPI仕様を取り込む

AnypointStudioにAnypointPlatformのアカウントの設定をした状態で行ってください。
AnypointPlatformのアカウントの設定は以下に載せています。

MulesoftでAPI開発～APIをCloudHubにデプロイ～

[File] -> [New] -> [Mule Project]

プロジェクト名を入力し、[+]ボタンをクリック

[from Exchange]を選択

ExchangeでAPI仕様を検索し、取込み対象を選択

DesignCenter上でAPI仕様を作成した際のユーザIDを選択し、
API仕様名を入力すると、自動で検索される。

取込み対象のAPI仕様を選択 -> [Add] -> [Finish]

[Finish]をクリック

これでAPI仕様を取り込んだプロジェクトが生成されます。

作成したプロジェクトの確認

PackageExplorer

このような感じになっています。

hello-mule.xml ではフローが自動生成されています（後述で中身見ていきます）
hello-mule[v1.0.0] ではDesignCenterで生成したAPI仕様のファイルがzip形式で取り込まれています。

自動生成されたフロー（hello-mule.xml）

3つのフローが自動生成されています。

(1)メインのフロー

メインのフローには以下の特徴があります。

APIkit Routerを含む
APIkit RouterにはリクエストされたAPIエンドポイントのパスごとに、
それぞれの専用のフローに割り振る役目があります
エラーハンドリングを含む
デフォルトでどのAPIにも必要となりそうなエラーハンドリングが生成されています。

コンソール用フロー

APIを起動した際、ExchangeのようなAPIコンソール画面を起動するためのフローです。
API起動後、{URL}/consoleにアクセスすると以下のような画面が起動し
APIの動作確認が可能となります。

APIエンドポイントのフロー
メインのフローにあるAPIkit Routerから呼び出されるサブフローとなります。
つまり/hogeのAPIエンドポイントへのリクエストはAPIkit Routerによって、
こちらのサブフローに処理が割り振られるようになっています。

また、TransformMessageオブジェクトには下図のように、
デフォルトでAPI仕様のsampleに記載したjson形式のレスポンスが設定されています。

まとめ

以上のようにAnypointPlatformのDesignCenterで記述したAPI仕様をベースとして、
AnypointStudioでプロジェクトを作成し、API実装ができる状態まで出来るようになりました。