Amplify + S3でSwagger UIのAPIドキュメントを簡単に共有する方法

この記事ではAmplifyとS3を組み合わせて、簡単にSwagger UIのAPIドキュメントをWeb上で共有する方法を紹介します。 Basic認証を設定することもできるので、開発チーム内での共有などに利用できると思います。

こが

2021.10.18

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

この記事ではAmplifyとS3を組み合わせて、簡単にSwagger UIのAPIドキュメントをWeb上で共有する方法を紹介します。
Basic認証を設定することもできるので、開発チーム内での共有などに利用できると思います。

Swaggerファイルの編集

今回使用するSwaggerファイルはこちらです。
~/work/swagger-ui-distというフォルダに置かれる前提で書いていきます。

{
  "swagger": "2.0",
  "info": {
    "title": "Amplify-TEST",
    "description": "Amplify-TEST",
    "version": "1.0"
  },
  "tags": [
    {
      "name": "Amplify-TEST"
    }
  ],
  "host": "localhost",
  "schemes": [
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/health-check": {
      "get": {
        "summary": "Health check endpoint",
        "description": "This api can be used to health check.",
        "operationId": "Amplify-TEST_HealthCheck",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {}
          }
        },
        "tags": [
          "Utils"
        ]
      }
    }
  }
}

私はVSCodeにSwagger viewerという拡張機能をインストールし編集しています。
shift + option + p（Macの場合）で簡単にプレビュー画面が開くので便利です。

Swaggerファイルを作成したら、Swagger UIに必要なファイルダウンロードします。
swagger-api/swagger-ui/distのファイルをダウンロード or git cloneしてください。
ダウンロードしたファイルを全て~/work/swagger-ui-dist配下に置いたあと、index.htmlを編集します。
SwaggerUIBundleのurlの指定を、./amplify_test.swagger.jsonに書き換えてください。

 ~~~     
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "./amplify_test.swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      });
      // End Swagger UI call region

~~~

以上でSwagger UIの準備は完了です。

S3バケットの作成

続いてAWSコンソールからS3バケットを作成します。
設定等は今回は全てデフォルトで問題ありません。

バケット作成後、下記コマンドでS3へ~/work/swagger-ui-dist配下のフォルダをアップロードします。（事前にAWS CLIの設定等が必要です）

cd ~
zip -rjq output.zip work/swagger-ui-dist
aws s3 mv output.zip s3://{作成したバケット名を指定してください}

S3の準備は以上で完了です。

Amplifyで新規アプリの作成

続いてAWSコンソールからAmplifyの新規アプリを作成します。
AWSコンソールのサービスからAWS Amplifyを選択し、サイドメニューからすべてのアプリを選択し、New Appボタンを押してください。

その後表示されるメニューからHost web appのボタンを押してください。

Develop without Git providerにチェックを入れ、Continueボタンを押してください。

App nameに任意のアプリ名を、 Environment nameは今回はtestとします。 ※ここで指定するEnvironment nameが作成するアプリのURLのプレフィックスとなります。
MethodはAmazon S3にチェックを入れ、Bucketには先程作成したバケットを選択し、Zip fileには先程アップロードしたoutput.zipを選択します。

作成されたアプリのドメイン、https://test.XXXXXXXXXXX.amplifyapp.comにアクセスしてください。

下記のように表示されるはずです。

Swaggerファイルの更新

Swaggerファイルを更新後、下記コマンドを実行してください。
今回はtitleをAmplify-TEST UPDATEに更新しています。

cd ~
zip -rjq output.zip work/swagger-ui-dist
aws s3 mv output.zip s3://{作成したバケット名を指定してください}
aws amplify start-deployment --app-id {作成されたアプリのドメイン`https://test.XXXXXXXXXXX.amplifyapp.com`のXXXXXXXXXXXの部分} --branch-name test --source-url s3://{作成したバケット名を指定してください}/output.zip

もう一度https://test.XXXXXXXXXXX.amplifyapp.comにアクセスするとタイトルが更新されているはずです。