💬

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

2022/08/16に公開

AWS

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

背景

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です。