前回の記事ではOpenAPIを利用したSpecの生成とそれを利用したプロキシ(Proxy)の生成を実施しましたが、皆さんはAPIを作成した後のAPIドキュメント(API Document)はどうしていますか？
実際に自分で書いて見ると分かると思いますが、意外と面倒ですよね。
面倒ですがAPIドキュメントを作らないと、実装者以外はAPIに対してどんなリクエストを投げれば良いのか分からず困ってしまいますね。
Apigeeでは、作るのが面倒なAPIドキュメントを生成する機能があるのをご存知でしょうか？
面倒なことは少しでも自動化したいと思いますので、今回の記事ではApigeeでOpenAPIを利用したAPIドキュメント生成をやって見たいと思います。
今回の流れは
- step1. Apigee EdgeからPortalを作る
- step2. 前回ImportしたSpecからAPIドキュメントを生成
となります
さあ、もっと有益なApigeeライフを営為するために。。。
レッツ、トライ！
目次
1.APIドキュメントの居場所、Portal
最初にDeveloper Portalを構築しないといけません。APIに関連する情報やAPIを公開する手段でありApigee Edgeの管理APIを利用し、APIを管理することができるなど色んな機能を取り込んでAPI専用ページを作成することができます。
詳細は下記のページを参照してください。
Apigee Docs – デベロッパー ポータルの紹介
Google Cloud – Apigee デベロッパー ポータル
1.1.まずはPortal作りから！
本課題、APIドキュメントを生成するために必要な基地を立てる必要があります。
左のメニューからPUBLISHを選択し、Portalsをクリックしましょう。
空っぽなので作りがいがありそうです。
Get startedを押しましょう。
幾つかの入力項目が表示されました。入力内容は下記を通りです。
① Portalの名前、ここの名前がPortalのアドレスに含まれます
② Portalの説明
③ Portalアドレスが表示されます
④ 現在、DeveloperProgramを作成したものがないため、Create a new~ を選択します。
※ DeveloperProgram
このプログラムを通してユーザーにIDを提供し、ポータル利用者としての登録することができます。
開発者プログラムを利用するポータルにアクセスが可能、複数のポータルが同じプログラムを使用することも可能です。
詳細はここを参照してください
Developer Programの選択後、Beta for Teams and Audiences欄が表示されます。
開発者と利用者の管理機能（Beta!!）を使用することができますが、今回はチェックを外しても大丈夫です。（この設定値の詳細はここを参照してください。）
入力が終わったので、Createボタンを押してポータルを生成します。
now Creating…
意外と簡単にできたので、足りないものは無いのだろうかと思ってしまいますね。
2.APIドキュメントの生成は、Portal
2.1.Spec(OpenAPI)からAPIドキュメントを！？
Portalを立てることに成功しました！であれば次はAPIドキュメントを生成しましょう
API管理はこちらのメニューとなります。
空っぽなので、生成するのみ。
おっと！！！
API Productだと。。。Specから作り出したプロキシ専用のもが無いので、作りましょう。
※ APIプロダクトとは何！？
API プロダクトはリソース（API プロキシなど）をバンドルします。これにより、クライアント アプリのデベロッパー向けに特定のアクセスレベルと機能が提供されます。API プロダクトは通常、一連の API プロキシとアクセス制限、API キー承認方法を指定することに加えて、バンドルのすべてのプロキシ用に必要なその他の構成を指定します。
Apigee公式ドキュメント、Apigee Docs – API プロダクトからの引用
同じカテゴリーにある、APIプロダクトを選択してから
＋ボタンをクリック
APIプロダクトを生成するためには下記の内容を入力します
① プロダクト名
② プロダクト表示名（プロダクト名と同じものを入力）
③ プロダクトの説明
④ デプロイ環境（デフォルト：test）
⑤ アクセス制限（Publicで実施しました）
⑥ APIプロキシ（Add a proxyをクリックすると下記の画面が表示されます）
今回APIドキュメント生成対象となるOpenAPIから生成したプロキシを選択
プロキシが設定されていることを確認後、右上にあるSaveボタンを押すとプロダクトが生成されます。
生成完了！
リストに生成したプロダクトが追加されていることを確認後、本作業へ〜！
2.2.課題達成の条件が整った！いざ！！API Document！！！
不足分の作業が終わったので、本作業へ戻ります。
ポータルを選択後、APIs → Get started
2.1で生成したAPIプロダクトを選択
Specが存在しない場合、前回の記事を参考に生成することをお勧めします。
今回は前の記事作成時に生成したものがあるので、それを利用することにします。
※ 他の項目はAPIプロダクトの内容が記入されます（修正したい場合、修正！）
Specを選択すると大事なところは終わったと思います。
Finishを押すとドキュメント生成が行われます。
ポータルはすでに動いているので、右上にあるLive Portalをクリックし、Portalを開き、確認するのみ！
3.APIドキュメントのお試し、Portal
画面が表示されたら、APIs → MockProduct → で進むとSpecと同じ匂いがする画面が表示されます。
ステップ、ワン
ステップ、ツー
本課題の終着駅、ここがAPIドキュメントページとなります。
左のAPIリファレンスから幾つか選んで内容確認をしましょう。
左のAPIから選択したものは’/user’APIです。
user項目に入力したテキストを結合して返してくれます。
適当に何かを入れて実行（Executeボタン押下）しました。
入力した文字が結合されて帰ってきました。
異常なし！
入力内容を変更してもう一回実行。
他のAPIの動作確認もこんな感じで行えば良いので、気楽に操作ができます。
あ、API実行に夢中だったので真ん中の画面をチェックしてませんでしたね、
忘れる前にどんな内容が表示されているか確認します。
画面中央にはAPI情報が表示されています。
Specでも似たようなものを確認できますが、それとは一部の内容(⑤がSpecには存在しない)が違いますね。
表示内容
① httpメソッドとAPI名
② リクエストを送信するバックエンドサーバのアドレス
③ リクエストに設定するパラメータ
④ OpenAPIで定義したレスポンスコードの説明
⑤ 認証に必要な条件（このAPIでは未定義であるため、None）
気になるところがあったので、他のAPIも確認して見ましょう。
このAPIはPOSTメソッドらしくリクエストボディを設定しないといけませんね、Try部分を見ると必須であることが伝わってきます。
このGETメソッドはパスパラメータですね、パラメータタイプが表示されるのでどんな形をしたパラメータが設定されるかが伝わってきます。
これでAPIの情報確認やAPI実行まで一通り確認しましたので、確認終了となります！
まとめ
何をしてから何をすれば良いのかがはっきりしていなかったため、実施順番が逆になっているところもありましたが、前回の記事で生成したSpecやプロキシのお陰で楽にできたと思います。
この課題を通して新しいApigeeの利用方法を知ったので、そこをもっと拡張させれば良いAPI管理体制を構築できると思います。
そろそろOpenAPIの作り方から始まるApigee利用を目指す必要がありそうですね、もっと有益なApigeeライフを過ごす手段として定着させるために！
では皆さん。。。次の記事でまた会いましょう〜