GitHub Actionsを使ってSwaggerをGitHub Pagesにホスティングする #GitHub

OpenAPI形式で書かれたAPI仕様書は、SwaggerUIでGitHub Pagesにホスティングできます。
今回は、そのGitHub PagesへのホスティングをGitHub Actionsを使って簡単にデプロイする方法をまとめます。

ディレクトリ構成

.
├── .github
│   └── workflows
│       └── deploy-to-github-pages.yml
└── openapi.yml

Workflow

.github/workflows/deploy-to-github-pages.yml

name: Deploy to GitHub Pages

on:
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize
      - closed
    paths:
      - openapi.yml
      - .github/workflows/deploy-to-github-pages.yml

jobs:
  deploy-to-github-pages:
    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 openapi.yaml --type yaml

      - name: Generate Swagger UI
        if: github.event.pull_request.merged == true
        uses: Legion2/swagger-ui-action@v1
        with:
          output: swagger-ui
          spec-file: openapi.yaml

      - name: Deploy to GitHub Pages
        if: github.event.pull_request.merged == true
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: swagger-ui

Legion2/swagger-ui-action

OpenAPIファイルからSwaggerUIを生成する処理。

peaceiris/actions-gh-pages

生成したSwaggerUIをGitHub Pagesにホスティングする処理。

Options	Description
github_token	`GITHUB_TOKEN`はGitHub Actions runnerで自動生成されるトークンであり、 Personal Access Tokenではない。`${{ secrets.GITHUB_TOKEN }}`を設定しておけば問題なし。
publish_dir	オプション名が紛らわしいが、sourceディレクトリを指定する。
destination_dir	今回はリポジトリ直下に配置しているが、destinationディレクトリを指定することもできる。
publish_branch	publishブランチの指定。デフォルトでは`gh-pages`ブランチにpublishする。
external_repository	他のリポジトリにデプロイすることもできる。その場合`deploy_key` もしくは`personal_token`で権限を設定する必要がある。

実行条件

onで設定しているWorkflowの実行条件：
以下2つとも条件が合致したとき。

mainブランチへのプルリクエストを作成・更新・マージしたとき
openapi.ymlかdeploy-to-github-pages.ymlに変更があるとき

ifで設定しているStepの実行条件：

Generate Swagger UIとDeploy to GitHub Pagesを実行するのはマージした時のみ

GitHub Pagesの設定

今回の場合、ブランチはgh-pages、ディレクトリは/(root)で設定する。
設定の詳細方法は下記参照。

GitHub Pagesの確認

GitHub Pagesの設定完了後、生成されたURLからホスティングされたSwaggerUIを確認することができる。
設定反映までに最大10分かかることがある模様。詳細は下記参照。

GitHub Actionsを使ってSwaggerをGitHub Pagesにホスティングする