Amplify Console とSwagger UIで常に最新のAPIドキュメントをWebから参照できるようにする

開発中のAPIドキュメントを自動でWeb上に公開するようにAmplify Consoleを使ってホスティング&設定をしてみました。IDとパスワード入力を必須にする設定も一瞬でできました。
2020.07.02

やりたいこと

  1. API 定義を Web上で閲覧できるようにする
  2. API 定義が更新されたら自動でWebページ上にも反映されるように設定する
  3. 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 ならね。

マネジメントコンソールの上部にあるドロップダウンメニューを開いて、上から4番目の"Password-protect your site"を選択、または左側のメニューから”Access Control”を選択します。

”Manage access”を押下します。

"Access Setting"をPublicly viewableからRestrictedへ変更します。

ID とパスワードを設定して完了です。

動作確認

先ほどの URL へ再度アクセスしてみましょう。

ID とパスワードの入力を求められます。

設定した ID とパスワードを入力してWebページが閲覧できれば成功です。

あとがき

今回はAmplify Consoleを使って静的なファイルをサクッとホスティング&自動デプロイする方法をご紹介しました。ビルドの設定を組み込めたりなどできることはまだまだたくさんありそうなので引き続き使ってみようと思っています。

また新しい発見があればブログにまとめたいと思います。

Reference List