はじめに
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のアカウントの設定は以下に載せています。
[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実装ができる状態まで出来るようになりました。