この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
やりたいこと
- API 定義を Web上で閲覧できるようにする
- API 定義が更新されたら自動でWebページ上にも反映されるように設定する
- Basic 認証を設定して限られた人のみがページを閲覧できるようにする
使うもの
- Amplify Console
- Github
- Swagger UI
Github レポジトリの Swagger 定義ファイル、swagger.ymlが更新されたら Web も自動で更新されるように Amplify Console でドキュメントのホスティング＆自動デプロイの設定をします。
Github レポジトリを用意する
Amplify Console と連携する Github レポジトリを用意します。 既存のものがあればそれを利用します。
後ほどこのレポジトリへ Swagger 定義等のファイルを Push するので先にローカル環境へクローンしておきましょう。
Amplify Console を設定する
AWS のマネジメントコンソールで Amplify を開いて”Connect app”を選択します。
次の画面でソースレポジトリの種類を選択できるので Github にチェックを入れます。初めて利用する場合はこの後 Github へのアクセス認証画面が立ち上がるので承認します。
レポジトリとブランチを選択します。
ビルドの設定は必要ないのでデフォルトの設定のまま次へ進みます。
Save and Deploy をクリックして Amplify Console 側の設定は完了です。
Swagger ファイルを作成
swagger.ymlを作成し、適当な API 定義を記述します。
openapi: 3.0.0
info:
title: app
version: 1.0
paths:
/:
get:
summary: Hoge API
responses:
"200":
description: ok
content:
application/json:
schema:
type: object
properties:
payload:
type: object
"400":
description: Bad Request
parameters:
- schema:
type: string
in: header
name: authorization
required: true作成した Swagger 定義はspec/ディレクトリ下に置きました。
パスを後ほど設定するのでどこに置いても特に問題ありません。
Swagger UI の設定
この部分はbuzztaikiさんの記事が素晴らしかったので引用させていただきました。
まず下のコマンドを実行してindex.htmlファイルを Gist から ルートディレクトリへコピーします。
curl https://gist.githubusercontent.com/buzztaiki/e243ccc3203f96777e2e8141d4993664/raw/0bcbbf52cf500221c0f26bbe81124be4f4c48249/swagger-ui.html > index.html以下の内容で index.html ファイルが作成されるのでswagger.ymlファイルのパスを修正します。
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Sample API</title>
<link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css" >
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body
{
margin:0;
background: #fafafa;
}
</style>
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"> </script>
<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
url: "spec/swagger.yml", // swagger.ymlのパス
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui
}
</script>
</body>
</html>以上をレポジトリにコミットしてみましょう。
Amplify Console 画面を確認する
指定したブランチにコミットがあるとAmplify Console上で自動ビルド＆デプロイが走ります。 今回は何もビルドしないのでデプロイはすぐに完了すると思います。
完了したら左下の URL をみてみましょう。
先ほど作成した”Hoge API”が表示されていれば成功です。
Swagger 定義を更新してみる
API 定義を更新したら Amplify Console の自動デプロイが正常に動作するか確認してみましょう。
swagger.yml の内容をこちらの PetStoreAPI に書き換えます。
変更をコミットして再度マネジメントコンソールを確認してみましょう。
ビルドが完了したら左下の URL から Web 画面を確認してみましょう。
PetStore の API に更新されていれば成功です。
これでレポジトリのswagger.ymlが更新されるたびにWebページ上のAPI定義も自動更新される設定が完了しました！
Basic 認証を設定する
開発中の API 定義は顧客や同僚など限られた範囲にのみ公開したいケースがあります。 ID とパスワードの入力を必須にする Basic 認証の設定も一瞬でできてしまいます。そう、Amplify Console ならね。
マネジメントコンソールの上部にあるドロップダウンメニューを開いて、上から４番目の"Password-protect your site"を選択、または左側のメニューから”Access Control”を選択します。
”Manage access”を押下します。
"Access Setting"をPublicly viewableからRestrictedへ変更します。
ID とパスワードを設定して完了です。
動作確認
先ほどの URL へ再度アクセスしてみましょう。
ID とパスワードの入力を求められます。
設定した ID とパスワードを入力してWebページが閲覧できれば成功です。
あとがき
今回はAmplify Consoleを使って静的なファイルをサクッとホスティング＆自動デプロイする方法をご紹介しました。ビルドの設定を組み込めたりなどできることはまだまだたくさんありそうなので引き続き使ってみようと思っています。
また新しい発見があればブログにまとめたいと思います。
7
