Swaggerで作成したAPI仕様書をGitHub Pagesにデプロイしよう！ #GitHubActions

概要

Swaggerで作成したAPI仕様書をGitHub Actionsを使ってGitHub Pagesにデプロイする方法について解説します

前提

GitHub Actionsに関する基礎知識を有している
openapi.ymlを作成済
Swaggerでドキュメントを自動生成する用のAPIを作成済み

ディレクトリ構成

ファイル構成は以下のとおりです

❯ tree
.
├── .github
│   └── workflows
│       └── deploy-swagger.yml
└── doc
    └── openapi.yml

実装するファイル一覧

deploy-swagger.yml

ワークフローの作成

SwaggerをGitHub Pagesにデプロイするワークフローを作成します
まず、swagger-cliをインストールし、doc/openapi.yml内に書いたドキュメントを静的ファイルとして出力し、swagger-uiというフォルダに格納します
その後、swagger-ui内の静的ファイルをGitHub Actions公式のartifactのactionを使ってartifact内に格納します
最後にartifact内の静的ファイルをGitHub Actions公式のdeploy-pagesを使ってGitHub Pages上にデプロイします

.github/workflows/deploy-swagger.yml

name: Deploy Swagger UI to GitHub Pages

on:
  push:
    branches:
      - develop
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Chekcout code
        uses: actions/checkout@v4
      - name: Install swagger-cli
        run: npm install -g swagger-cli
      - name: Generate Swagger UI
        uses: Legion2/swagger-ui-action@v1
        with:
          output: swagger-ui
          spec-file: doc/openapi.yml
      - name: Upload Documents
        uses: actions/upload-pages-artifact@v3
        with:
          # 絶対パスを指定
          path: swagger-ui

  # Deploy the artifact to GitHub pages.
  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4