ApigeeのSpecでOpenAPIを利用し、Proxy生成！

注意

この記事は2019年6月10日に更新されたもので、内容が古い可能性がありますのでご注意ください。

ApigeeでのAPI構築時、プロキシを１から作り上げると言う過程がめんどくさいと思う時があると思います。
そのプロキシ構築を楽にする事ができる手段を調べたところOpenAPIとApigeeのSpecと言う機能を利用するとYAMLに記述されている内容を基にプロキシ(Proxy)作成が楽にできると言う事を知りました。

と言う事をキャッチしたのであれば確かめないといけません。
と！その前に何点か確認してから始めようと思います。

1.使用するものは何？
2.これからやって見よう〜！
まとめ

1.使用するものは何？

1.1.Apigee

APIのAPIによるAPIのための専門プラットフォームです。
GCPのGoogle Cloud Endpointsとの比較を含めApigeeの理解を深める事ができるapps-gcpの記事があるので参考してください。
Cloud Endpointsと比較しながらApigee概要を学ぶ

1.2.Apigee Spec

ウェブ画面からOpenAPIの作成や編集ができるエディターを提供し、作成したAPIの動作確認やプロキシ生成などができるApigeeの機能。

1.3.OpenAPI

YAML又はJSON形式でREST APIを設計するフォーマット。
Apigeeではこれを利用してプロキシの生成やAPIドキュメントを生成する事が可能。

OpenAPIの詳細は下記のページを参考にしてください。
特にApigeeの公式ドキュメントをお勧めします。
Apigee Docs – Overview of API design
GCP – Cloud EndpointsのOpenAPI説明
 Swagger – What is OpenAPI?

2.これからやって見よう〜！

SpecのImportからOpenAPIの動作確認とプロキシの生成や動作確認まで、これらを確認するためには下記のステップを踏みながら進みます。

step1 Specの生成（YAMLを使いImportする）
step2 生成したSpecでOpenAPIの動作確認
step3 生成したSpecを利用し、プロキシを生成する
step4 プロキシのAPIを叩いてSpecで試したものと同じ処理をするのかを確認する

ApigeeのSpecとOpenAPIを利用すると言う事を知ったのはともかく、本課題の目標であるプロキシ生成にはそれらをどう利用するのかが知りたい。
先にApigeeのSpecで使用するYAMLを準備しないといけませんが、hello worldサンプルがこちらに存在します。
ここにあるYAMLサンプルであれば安心して試す事ができます。

2.1.最初はSpecをImportし、OpenAPIの動作確認を実施

まず、Apigee Edgeコンソールを開きましょう。
apigee edgeへログイン
ログイン後、メインページへ〜

メインページが表示されたなら’Specs’をクリック
※ このUIはNew UI（デフォルト）です、Old UIで開かれている場合はNewに切り替えましょう。

サンプルからmocktarget.yamlをImportしSpecを作成するので、Import URLを押しましょう。

Import Name : Spec名を入力
Import URL : サンプルからmocktarget.yamlのRAWアドレスを入力
入力してからImportボタンを押すとSpecが生成されます。

生成されたSpecを確認しましょう。

表示される画面は大きく３箇所で分けられています。
① 編集エディター
② Specの名前やホストアドレス、説明（YAMLにこれらの情報が含まれている）
③ OpenAPIで定義されているAPIのリスト

Importしたサンプルに定義されているAPIが表示されましたが、各APIがどんな処理を行うものなのかが分かりません！
１つずつ直接叩いて見るしかないのか？

直接このAPIを実行して見る必要があるかと思いましたが、詳細が分かるドキュメントがありました。
サンプルの説明は公式ドキュメントから確認ができるので、各APIを調べることができます。

じゃ、何か１つ選んで叩いて見ましょう。

パラメータに名前を入れると挨拶をしてくれるAPI
API実行のため、try it out！

userと言うパラメーターを入力するのですが、YAMLではどんな風に定義されているのか確認したいですね。

userパラメーターは文字入力が可能で、必須項目ではない
それ以外のパラメーターは存在しないので、userパラメーターのみ入力すればOKでした。

確認のため、何かを入れて実行します。

userパラメーターが設定されているリクエストのレスポンスが戻ってきました。
Hello, master!
リターンコードも200で正常終了、他のAPIもこう言う感じでやるのか確認しましょう。

ステータスコードとメッセージを表示するAPI
400を入れたらそれが帰ってくるのでしょうか～？

通信自体は200で成功、だけど中身にステータスコードに対する内容が含まれていますね。

今回は200で実行してみましたが、これだけじゃメッセージが如何の斯うのと言う内容確認が出来ません。。。
プロキシを生成してデバッグする必要がありそうなので、引き続き作業を進めます。
本課題の最終目標が目の前にあります。

2.2.Specでプロキシを起こす！？

上記のImportでSpecを生成しました。
それを利用すればプロキシを作れると言うことなので、これからトライします。

サンプルのYAMLで生成したSpecから右側にある手裏剣のようなアイコンをクリックしましょう。

！？！？
Request has been terminated Possible causes: the network is offline, Origin is not allowed by Access-Control-Allow-Origin, the page is being unloaded, etc.
なんだこれは！？サーバーがオフライン？
赤枠の右上にある’✖︎’をクリックして閉じて見ると

上記のアドレスが指定されていることが分かります。
デフォルトかな？
入って見ました。

結果、入れず。。。the network is offline。。
※ Specからプロキシ生成ではなくプロキシメニューからプロキシ生成を行うと上記の事象は発生しません。

確認が終わったので、本作業へ戻り下記の流れを実施します。
仮のもの　→　クリア　→　OpenAPI選択　→　上の過程で生成したSpecを指定

YAMLファイルをアップロードすることもSpecをImportするときの様にURLからでの指定も可能です。
今回は生成しといたSpecがあるのでそれを選びます。

指定が終わるとドキュメントのアドレスが表示されますが、入れません。
これはプロキシとSPECを繋げるために必要なキーで、一つのSPECから複数のプロキシを生成した時にこのキーを使い同じSPECへ関連付ける事が出来る様です。
これの詳細を調べるのは現在の課題と距離があるので、省略して次の作業へ進みましょう。

ここからはYAMLに定義された内容が各項目に表示されるため、内容確認後
問題なければNextをクリック。

YAMLに定義されているAPIが表示されました。
もし全部いらない場合、この段階で使いたいものだけを選択しましょう。
最初は不要でも後々必要になったりするものもあるんですよね、選択は慎重に。

このお試しはSpecからプロキシ生成を体験するため認証周りを気にせずにスルーパースを選びましたが、万が一、セキュリティーが気になる方はApikeyを用意たアクセス制御記事をご覧になってください。

httpのみでの検証で問題ないのでセキュアのところは解除しても問題ありません。

どの環境へデプロイするかを選択するのですが、デフォルトにTestが設定されているのでそのままで大丈夫です。

これでプロキシ設定が終わり望んでいる通りにプロキシができているのかを確かめる番です。

2.3.Specから生成したプロキシで！API！！

無事にプロキシが生成されたことをこれから確認しましょう！

デプロイ後、プロキシ画面が表示されるので、欲しがっていたプロキシが存在することを確認！
そして中にDive！

概要タブに表示されたこのURLがAPI動作確認で使用されます。
トレースタブにも同じURLが表示されるので、そのタブでURLをコピーしましょう。

DevelopタブにはYAMLに定義されていたプロキシの各APIがずらり！
この中からさっき動かしてみたAPIがあるか探して見ましょう。

プロキシが出来上がったところで、Apigeeの動作確認を行う番です。
ちゃんとレスポンスが戻ってくるかを確認するために、まずはトレースをONにします。

トレースON
※ ここで、注意点が１つ！
トレースが始まると制限時間が設定されるため、ONにした状態であれこれやっているといつの間にかOFFになりトレースできなくなるので時間の確認をしながら進めましょう。

動作確認をするためにApigeeのRestクライアントを利用しました。
https://apigee-rest-client.appspot.com/
これでREST APIをコールする道具も準備できたので、APIを叩きましょう。
さあ、レッツゴー！

まずは最初に実施した入力内容返しを確認します。
userと言うパラメーターにyour my masterを設定したらそのまま帰ってくるはずなので、期待値であるHello, your my masterが帰ってくると成功。
※ 使用するAPIの指定やパラメーターの設定はSpecでAPI動作確認を行った時に表示されていたURLを参考にしてください。