GitHub PagesでSwaggerをホスティングするGitHub Actionsの書き方

チーム開発をする時にAPI仕様書をOpenAPI形式で書くことが多いかと思います。
その場合によく問題になるのはその仕様書をSwaggerでホスティングする場所です。
チームの人数が少なければ、各自の環境でdockerなどを使ってSwaggerを立ち上げても良いですが、人数が多くなるとどこかでホスティングしたくなります。

この記事ではGitHub Pagesでホスティングするための設定を紹介します。

設定例

以下のYAMLファイルをGitHub Actionsで実行することで簡単にSwaggerをGitHub Pagesでホスティングできます。
GitHub Pagesの公開設定をPrivateにすることで、特定の組織に属している人のみに公開するという認証もできます。

name: "swagger release"

on:
  pull_request:
    branches:
      - 'main'
    types: [opened, synchronize, closed]

jobs:
  swagger-validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install swagger-cli
        run: |
          npm install -g swagger-cli

      - name: Validate swagger files
        run: |
          swagger-cli validate -d swagger.yaml --type yaml --format 3

  swagger-release:
    if: github.event.pull_request.merged == true
    needs: swagger-validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install swagger-cli
        run: |
          npm install -g swagger-cli

      - name: Inject Swagger static files
        run: |
          wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v4.1.0.tar.gz
          tar -zxvf v4.1.0.tar.gz swagger-ui-4.1.0/dist/
          cp swagger-ui-4.1.0/dist/* docs/

      - name: Combine Multiple Swagger Files
        run: |
          swagger-cli bundle swagger.yaml  --outfile docs/swagger.yaml --type yaml --format 3

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

応用編(独自ドメインでホスティングする)

上記のままですと、公開設定がPrivateの場合はホスティングされるドメイン名が適当な英単語をつなげたものになってしまい、少々不格好です。
そのため、独自ドメインでのホスティングを行ってみます。
まずはホスティングしたいドメインの情報を以下のようにYAMLファイルに追加します。

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
          cname: <ホスティングしたいドメイン> # この行を追加

その後、そのドメインに以下のようなCNAMEレコードを追加します。

<ホスティングしたいドメイン> 300 IN CNAME <リポジトリが所属するOrganization名>.github.io.

その後数分まてば独自ドメインでのホスティングが完了します。

参考: