💬

PRをトリガーにOpenAPIのURLをamplifyで自動ホスティングして、最高の開発環境を手に入れた話

2022/08/16に公開約3,900字

このツイートの通り、快適な開発環境を手に入れることが出来たので今回はその方法について書きます。

https://twitter.com/yui_active/status/1539862057042210816?s=20&t=zZdTBSGpepe-1e0Ujjsgng

背景

OpenAPIを導入しているプロジェクトがあったのですが、中身の確認のためにはyamlファイルを読むか、SwaggerEditorを利用するしか方法がありませんでした。
そのため直感的に確認が出来ず、APIの仕様のレビューだけでも時間がかかってしまっていました。
そこで、OpenAPIの変更をコードベースではなく、UIでわかりやすく確認することにしました。
そのためにamplifyを使ってPRを上げたタイミングで、OpenAPIに関するディレクトリをホスティングして、確認用URLを発行することにしました。

ディレクトリ構成

今回はRailsのプロジェクトにdocsというフォルダを作り、その中にOpenAPIを入れているような構成でした。

├── docs
│   ├── openapi
│   │   ├── openapi.yaml
│   │   └── index.html // 今回のために作成したもの(後述)
│   └── README.md
└── app
└── bin
└── config
// 以下略

SwaggerUIを導入する

まずは、OpenAPIのyamlファイルを見やすくするために、SwaggerUIを導入します。

https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md を参考に、yamlファイルと同じ階層にindex.htmlを作成し、以下を貼り付けます。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="description" content="SwaggerUI" />
    <title>SwaggerUI</title>
    <link
      rel="stylesheet"
      href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css"
    />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script
      src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js"
      crossorigin
    ></script>
    <script
      src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-standalone-preset.js"
      crossorigin
    ></script>
    <script>
      window.onload = () => {
        window.ui = SwaggerUIBundle({
          url: "https://petstore3.swagger.io/api/v3/openapi.json", // ←ここを変更する
          dom_id: "#swagger-ui",
          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
          plugins: [SwaggerUIBundle.plugins.DownloadUrl],
          layout: "StandaloneLayout",
        });
      };
    </script>
  </body>
</html>

index.htmlを開いて、以下のようなページが見えれば正しくSwaggerUIが読み込めています。後はURL部分を変更するだけ。

上記のURLを正しいURLに変更します。私の場合だと、openapi.yamlを開きたいので、url: "openapi.yaml",のように変更します。(docs/openapiをルートとしてホスティングする予定なので、パスはopenapi.yamlだけで大丈夫です。)
現時点だとまだホスティングしていないため、index.htmlを開いても何も見えませんがそれでOKです。

amplifyを利用してモノレポホスティングをする

amplifyを開いて新しいウェブアプリケーション→ウェブアプリケーションをホストをクリック。

使っているgit管理サービスを選択して続行。

リポジトリを選択

今回はモノレポ構造なので、monorepo を接続しますか? フォルダを選択してください。の項目にチェックを入れ、ホスティングしたいディレクトリを入力します。

AWS Amplify がプロジェクトのルートディレクトリでホストされているすべてのファイルを自動的にデプロイすることを許可にチェックを入れて次へ。
最後に確認して保存してデプロイを押せばデプロイ完了です。

amplifyでプレビュー設定をオンにする

PRを上げると自動デプロイが走るようにしたいので、プレビュー設定をオンにします。
先程作成したアプリの設定からプレビューをクリック。

ブランチを選択して、プレビューステータスを有効にして保存。

これを有効にすると、指定のブランチに向けてPRを上げた時点で以下のように一時的なURLが発行され、OpenAPIの変更をUIで確認することが出来ます。便利!!

amplifyでベーシック認証をかける(オプショナル)

今回は外部にAPIの仕様が漏れてはいけないので一応ベーシック認証をかけました。

アプリの設定からアクセスコントロールをクリック。

アクセスの管理をクリック。

アクセス設定を制限に変えて、ユーザーネームとパスワードを入力して保存したら完了です。

あとがき

これで、まずはAPIの具体的な仕様をyamlで書く→発行されたURLを皆に共有→合意が取れたら開発という流れが組めるようになり、非常に開発体験が良くなりました。
今後もこういうちょっとした改善は続けていきたいですね。

ではでは、最後までお読みいただきありがとうございました。

Discussion

ログインするとコメントできます