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

背景・目的

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

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

実践

1. GitHubリポジトリの用意

専用のリポジトリを作成します

1. 「Create a new repository」をクリックします

2. 下記を入力し、「Create repository」をクリックします

   • Repository name
   • 公開/非公開
   • README file
     

3. git cloneします

   [e-mail]:XXXXswagger-test.git
   

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

2. Swagger/OpenAPI ドキュメントの作成

1. swagger-tutorial.yamlファイルを作成します
2. 以前使用したこちらを再利用します

   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
   

3. プレビュー（Shift + option + p）で確認します。問題なさそうです
   

3. GitHub Actions の設定

1. .github/workflows/フォルダを作成します
2. swagger.ymlを作成します

   swagger-test % cd .github/workflows 
   workflows % touch swagger.yml 
   

3. 下記の内容を記載します

   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のリポジトリに移動します

2. 「Settings」をクリックします

3. ナビゲーションペインで「Pages」をクリックします
   

4. Sourceでは、「Deploy from a branch」、「gh-pages」ブランチの「/root」フォルダを選択し、「Save」をクリックします
   

5. GitHub Actionsの設定

1. 「Settings」をクリックします
2. 「Actions」＞「General」をクリックします
3. Workflow permissionsで、「Read and write permissions」を選択し、「Save」をクリックします
   

5. コードをプッシュ

1. リポジトリにPushします

   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 % 
   

2. GitHub Actionsも成功しました
   

6. Swaggerドキュメントの確認

1. 「Settings」をクリックします
2. GitHub Pagesにリンクが表示されるので、「Visit site」をクリックします
   
3. 表示されました
   

考察

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

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

参考