GitHub ActionsでSwagger UIをGitHub Pagesにデプロイしてみた

# 背景・目的
以前、OpenAPIとSwaggerについて整理し、基本的な動作を確認しました。

https://qiita.com/zumax/items/ff28a671b5242f70fb74

今回は、SwaggerのドキュメントをGitHub Actionsを使って自動生成し、GitHub Pagesを通じて公開する手順を試してみます。


# 実践

## 1. GitHubリポジトリの用意
専用のリポジトリを作成します
1. 「Create a new repository」をクリックします
1. 下記を入力し、「Create repository」をクリックします
    - Repository name
    - 公開/非公開
    - README file
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/7762f2c4-481f-b718-8182-6058354ff3c4.png)
1. `git clone`します
    ```bash
    git@github.com:XXXXswagger-test.git
    ```

1. ダウンロードしたプロジェクトをVSCodeで参照できるように設定しておきます

## 2. Swagger/OpenAPI ドキュメントの作成
1. `swagger-tutorial.yaml`ファイルを作成します
1. 以前使用した[こちら](https://qiita.com/zumax/items/ff28a671b5242f70fb74#parameters-and-responses)を再利用します
    ```yaml
    openapi: 3.0.0
    info:
      version: 1.0.0
      title: Simple Artist API
      description: A simple API to illustrate OpenAPI concepts
    
    servers:
      - url: https://example.io/v1
    
    # Basic authentication
    components:
      securitySchemes:
        BasicAuth:
          type: http
          scheme: basic
    security:
      - BasicAuth: []
    
    paths: 
      /artists:
        get:
          description: Returns a list of artists
    
          parameters:
            - name: limit
              in: query
              description: Limits the number of items on a page
              schema:
                type: integer
            - name: offset
              in: query
              description: Specifies the page number of the artists to be displayed
              schema:
                type: integer
    
          responses:
            '200':
              description: Successfully returend a list of artists
              content:
                application/json:
                  schema:
                    type: array
                    items:
                      type: object
                      required:
                        - username
                      properties:
                        artist_name:
                          type: string
                        artist_genre:
                          type: string
                        albums:
                          type: integer
                        username:
                          type: string
            '400':
              description: Invalid request
              content:
                application/json:
                  schema:
                    type: object
                    properties:
                      message:
                        type: string
    ```
1. プレビュー（Shift + option + p）で確認します。問題なさそうです
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/6bdebb75-d262-6ba4-ed41-862c53a51c32.png)


## 3. GitHub Actions の設定
1. `.github/workflows/`フォルダを作成します
1. `swagger.yml`を作成します
    ```bash
    swagger-test % cd .github/workflows 
    workflows % touch swagger.yml 
    ```
1. 下記の内容を記載します
    ```yaml
    name: Deploy to GitHub Pages
    
    on:
      push:
        branches:
          - main
        paths:
          - openapi.yml
          - .github/workflows/swagger.yml
    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout code
            uses: actions/checkout@v4
    
          - name: List files in current directory
            run: ls -R
    
          - name: Install swagger-cli
            run: |
              npm install -g swagger-cli
    
          - name: Validate Swagger Files
            run: |
              swagger-cli validate -d swagger-tutorial.yml --type yaml
    
          - name: Generate Swagger UI
            uses: Legion2/swagger-ui-action@v1
            with:
              output: swagger-ui
              spec-file: swagger-tutorial.yml
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    
          - name: Deploy to GitHub Pages
            uses: peaceiris/actions-gh-pages@v3
            with:
              github_token: ${{ secrets.GITHUB_TOKEN }}
              publish_dir: swagger-ui
    ```

## 4. GitHub Pagesの設定
1. GitHubのリポジトリに移動します
1. 「Settings」をクリックします
1. ナビゲーションペインで「Pages」をクリックします
    <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/2fcb7b2f-74f9-c303-e59e-57db2d8d97c8.png" width=200 />

1. Sourceでは、「Deploy from a branch」、「gh-pages」ブランチの「/root」フォルダを選択し、「Save」をクリックします
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/123d5d61-1656-15c3-27ba-9e619055430d.png)

## 5. GitHub Actionsの設定
1. 「Settings」をクリックします
1. 「Actions」＞「General」をクリックします
1. Workflow permissionsで、「Read and write permissions」を選択し、「Save」をクリックします
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/31d36318-5c18-9fd2-35b6-0850d5151a12.png)


## 5. コードをプッシュ
1. リポジトリにPushします
    ```bash
    swagger-test % git add .
    swagger-test % git commit -m "Add swagger.yaml and GitHub Actions workflow"
    [main XXXX] Add swagger.yaml and GitHub Actions workflow
     2 files changed, 98 insertions(+)
     create mode 100644 .github/workflows/swagger.yml
     create mode 100644 swagger-tutorial.yaml
    swagger-test % git push origin main
    Enumerating objects: 7, done.
    Counting objects: 100% (7/7), done.
    Delta compression using up to 8 threads
    Compressing objects: 100% (4/4), done.
    Writing objects: 100% (6/6), 1.33 KiB | 454.00 KiB/s, done.
    Total 6 (delta 0), reused 0 (delta 0), pack-reused 0
    To github.com:XXXXX/swagger-test.git
       cd71ce9..8268147  main -> main
    swagger-test % 
    ```
1. GitHub Actionsも成功しました
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/046abb8b-a94d-4e46-4d75-1949115a99cb.png)


## 6. Swaggerドキュメントの確認
1. 「Settings」をクリックします
1. GitHub Pagesにリンクが表示されるので、「Visit site」をクリックします
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/70687e87-c4b5-bde7-8248-aec6263d6b2b.png)
1. 表示されました
    ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/206276/a2507069-5406-9f44-1481-49116cb028d3.png)

# 考察
今回、GitHub ActionsでSwagger UIをGitHub Pagesにデプロイしてみました。GitHub Actionsを使うことで、変更に応じて自動的にデプロイされる環境を構築できました。また、gh-pagesブランチを使って、mainブランチと分離できました。

Swagger UIのホスティングは、APIドキュメントをすぐにWeb上で確認できるようにする点で便利です。今後、API仕様の更新があった場合も、GitHub Actionsのワークフローにより自動的に反映されるため、メンテナンス作業が簡単にできると考えます。

# 参考
https://qiita.com/zumax/items/ff28a671b5242f70fb74

https://docs.github.com/ja/pages/getting-started-with-github-pages/about-github-pages

https://zenn.dev/yuki_tu/articles/11618e3bd6fcf2

https://docs.github.com/ja/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site

https://docs.github.com/ja/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site