まず初めに

この記事では OpenAPI を S3 に GitHub Actions を用いて自動デプロイすることを目的に記載しています。

なぜ自動デプロイさせたかったのか

クライアント側(フロント開発やアプリ開発など)への連携のしやすさと手動アップロードによるミスやコストの削減につながると思い自動デプロイできるように構成を考えてみました。
またAPIドキュメントの生成、表示にはRedocを利用し、S3は静的ホスティング活用し、社内IPからのみアクセスが可能な構成に想定しています。

要件としては

masterへのマージをトリガーにし、正式なドキュメントがアップロードされるようにします。
workflow_dispatchを設定手動でも実行できるように設定します。
プルリクエストに対してのレビュー指摘をもらい、修正しプルリクエストが更新されたタイミングでS3にデプロイしなおします。

S3の具体的なディレクトリ構成

(ルート)
 L master/
    L index.html
    L api.yml
 L pull_request/
    L feature-branch-name/
        L index.html
        L api.yml

対象者

OpenAPI を使用しているがクライアント(アプリ開発やフロント開発など)への共有の仕方に困っている
GitHub Actionsを学び始めた人

この記事で説明すること

GitHub Actions を用いた S3へのデプロイ構成について
設定するActionsの説明

この記事で説明しないこと

AWSリソースの作成方法
GithubのSecretsの設定方法
redocについての説明

まずは全体像

ProductCode

apiを提供するプロダクトと仮定します。
プロダクトコード内に docs/openapi/ のようなディレクトリを作成します。
プロダクトコード内に .github/ のようなディレクトリを作成します。

Github

GithubActionに設定するファイルを作成します。
- プルリクエストが作成・更新された際にフックするAction
  - pull-request-deploy-openapi-files-to-s3.yml
- マスターにプッシュされた際にフックするAction
  - master-deploy-openapi-files-to-s3.yml

pull-request-deploy-openapi-files-to-s3.yml (あくまでサンプルコードとなります。)

name: pull-request-deploy
on:
  pull_request:
    types: [opened, synchronize]
    branches-ignore:
      - master
    paths:
      - 'docs/openapi/**'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
      - uses: actions/checkout@v3

      - name: Deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: aws s3 sync --delete --region ap-northeast-1 ./docs/openapi/ s3://api/openapi/pull_request//${{ github.head_ref }}/

master-deploy-openapi-files-to-s3.yml (あくまでサンプルコードとなります。)

name: master-deploy
on:
  push:
    branches:
      - master
    paths:
      - 'docs/openapi/**'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
      - uses: actions/checkout@v3

      - name: Deploy
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: aws s3 sync --delete --region ap-northeast-1 ./docs/openapi/ s3://api/openapi/master/

各コマンドについての説明

pull_request: types: [opened, synchronize]
- プルリクエストが作成された時、プルリクエストに変更があった時にGithubActionが動く
- 詳しくはこちら
　branches-ignore:　master
- pull_request作成タイミングで対象のブランチがmasterの場合除外するようにする
paths: 'docs/openapi/**'
- 特定のパス配下の変更を検知しGithubActionが動く
env: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
- ${{ secrets.AWS_ACCESS_KEY_ID }}
- Github上で設定した、Secretsを参照します。
- 詳しくはこちら

S3

S3 Bucketを作成します。
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- を取得し, GithubのSetting内にあるSecretsに設定します。

考えてみて

今回初めてGitHub Actionsに触れたのですが、各ブランチや特定のアクションにフックできるのはとても便利に感じました。

また、S3に自動デプロイできるのは便利なのですが、今回は削除については考慮していないので今後の課題点としてあります。(プルリクエストがクローズするタイミング等でS3から削除するなどできそうですね)