この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
10月29日にアナウンスがあったこちらを試してみました。
どういう仕組みか簡単に述べると、
- aws-api-gateway-developer-portal をデプロイすると ポータルサイトのS3バケット と コンテンツ（swaggerファイル）用のS3バケット が生成される
- API Gateway で、swaggerファイルをエクスポートする
- 1で生成された コンテンツ用のS3バケット に swagger ファイルをアップロードする
ポータルサイトは S3 の静的ウェブサイトホスティングで公開されており、そこにアクセスするとAPI仕様を見ることができる、というものでした。触った感触だと、API Gateway ですでに構築された APIの仕様をすばやく展開できるため、一般公開しているAPIの仕様を見てもらう用途で活躍しそうです。
本記事では、手順に沿って既存の API Gateway の API 仕様をポータルサイトに載せるところまでやってみます。最終的には以下のようなサイトにアクセスできるようになります。
利用したもの
- ガイド：Use the Serverless Developer Portal to Catalog Your API Gateway APIs - Amazon API Gateway
- pip (18.1)
- AWS CLI (aws-cli/1.16.26 Python/3.6.5 Darwin/18.2.0 botocore/1.12.15)
開発者ポータルを作成する
先にサイトを構築してから swagger ファイルをアップロードしていく方式のため、まずは開発者ポータルを構築します。
AWS SAM
インストールします。私の環境では npm でインストールした古い AWS SAM が残っていたのでまずはそれの掃除からやりました。
npm uninstall -g aws-sam-local次に pip で最新の AWS SAM CLI をインストールします。
pip install --user aws-sam-clipip のユーザーディレクトリにパスを通します。fish shell の場合は以下。
## anyenv - pyenv init - fish
#### pyenv の設定…
#### pyenv の設定…
set user_base_path (python -m site --user-base)
set -x PATH $user_base_path/bin $PATHsam コマンドが叩ければOKです。
sam --version
SAM CLI, version 0.6.1開発者ポータルソースコードリポジトリを clone してデプロイ
まずこのリポジトリを clone します。
ghq get git@github.com:awslabs/aws-api-gateway-developer-portal.git次に、AWS SAM CLI を使ってデプロイします。このとき、{your-lambda-artifacts-bucket-name}、つまりテンプレートファイル用のバケットをあらかじめ作っておきます。{your-lambda-artifacts-bucket-name} と {custom-prefix} は各々の環境に合うよう置き換えてください。
sam package --template-file ./cloudformation/template.yaml --output-template-file ./cloudformation/packaged.yaml --s3-bucket {your-lambda-artifacts-bucket-name}
sam deploy --template-file ./cloudformation/packaged.yaml --stack-name "dev-portal" --capabilities CAPABILITY_NAMED_IAM --parameter-overrides DevPortalSiteS3BucketName="{custom-prefix}-dev-portal-static-assets" ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts"これを実行すると開発者ポータルのサイトができあがります。マネジメントコンソールの CloudFormation をみてみましょう。dev-portal というスタックがあるはずです。
いろいろなリソースを作っているみたいですね。 WebsiteURL がポータルサイトのURLなのでアクセスしてみましょう。
ポータルサイトにアクセスできればOKです。
API Gateway の swagger ファイルをコンテンツとしてアップロード
次はポータルサイトにコンテンツを上げます。
- API Gateway の API を作成し、デプロイする
- APIキーを発行する
- swagger エクスポートする
という流れです。APIキーは、ポータルに登録・ログインすることで利用者が見られるようになります。そうして手に入れたAPIキーを使って、公開されているAPIにアクセスします。
API Gateway の API を作成する
簡単なAPIを定義しました。デプロイまでやってしまいます。
APIキーを発行する
API Gateway ＞ Usage Plans で利用プランを作成します。先程デプロイしたAPIのステージに関連付けます。動作確認目的ですので、利用レートなどはなんでもOKです。premium プランを作成しました。
API Gateway ＞ API Keys で新しいAPIキーを作成します。先程作成した premium プランを関連付けます。
swagger ファイルをエクスポートする
API Gateway ＞ 作成した API ＞ Stages ＞ エクスポートしたいステージ ＞ Export タブと選んで、「Export as Swagger + API Gateway Extensions」を選んでjsonファイルをダウンロードします。
コンテンツアップロード
あとは、エクスポートしたファイルをアップロードします。アップロード先は決まっていて、sam deploy のときに指定した ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts" の catalog フォルダです。
ポータルサイトにアクセスしてみましょう。上部メニューから「API」を選びます。アップロードしたAPIの定義が swagger UI で見られるはずです。
さらに、ここから Register、SignIn を行うことでAPIキーが取得でき、ポータルサイトへ訪れた人が実際にAPIを叩くことができます。
まとめ
APIのポータルサイトを構築し、そこへ API Gateway で作成したAPI定義をアップロードして閲覧することができました。一般公開するAPIの仕様を見せる場所としてお手軽に構築でき、APIの開発者はドキュメント作成などの作業に時間を取られることがありません。
ポータルサイトのリポジトリによるとカスタマイズもできるようですので、引き続き以下のようなことについて試してみたいと思います。
- ポータルサイトのUIをカスタマイズする
- サインインしたユーザーのみにAPIを見せる、といったことができるか
- S3の前段に CloudFront を挟めるか（WAFをアタッチしてIPアドレス制限などができるようになるため）
- API Gateway から出力したものではない swagger ファイルでもいけるかどうか
クローズドなAPIについてもこの仕組で安心して利用できることがわかれば、用途が広がりそうですね。
2
