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

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

#Swagger

#GitHub

#Amplify Console

#AWS Amplify

#AWS

2020.07.02

この記事は公開されてから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>

以上をレポジトリにコミットしてみましょう。