🚢

Github Action でopenapi.yaml を自動表示させる

に公開
CI/CD
OpenAPI
githubaction
tech

はじめに

OpenAPIでAPI設計とGoでの自動型生成を行っております。
その過程でmainブランチのOpenAPIをGithubPageとして公開する方法について調べました

前提条件

  • Golang
  • OpenAPI
  • Redoc

プロジェクト構造

projectname/
├── .github/
│   └── workflows/
│       └── openapi-page.yml    # GitHub Actions ワークフロー
├── backend/
│   ├── openapi.yaml           # OpenAPI 仕様書
│   ├── Makefile              # ローカル開発用コマンド
│   ├── cmd/api/main.go       # メインアプリケーション
│   └── internal/
│       ├── api/generated.go  # OpenAPI から生成されたコード
│       └── http/
│           ├── routes.go
│           └── handler/
│               └── health.go
└── README.md

OpenAPI 仕様書の例

現時点ではhelthcheckしかないですが、、、

openapi: 3.0.3
info:
  title: AI Plan Chat API
  description: タスク生成アプリのAPI
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Development server
paths:
  /health:
    get:
      summary: Health check endpoint
      description: Health check のためのエンドポイント
      operationId: GetHealth
      responses:
        '200':
          description: Successful health check
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"

GitHub Pages の設定

Step 1: リポジトリ設定

  1. GitHub リポジトリの Settings タブに移動
  2. 左サイドバーの Pages を押下
  3. Source で GitHub Actions を選択
  4. Save を押下

この設定により、GitHub Actions からのデプロイが可能になります。

GitHub Actions ワークフロー詳細解説

ワークフローファイル全体

.github/workflows/openapi-page.yml:

一旦全体像を示します

name: Deploy OpenAPI Docs to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Generate API Documentation
        run: |
          mkdir -p docs
          npx @redocly/cli build-docs backend/openapi.yaml --output docs/index.html
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./docs
      
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

トリガー設定の解説

on:
  push:
    branches:
      - main          # main ブランチへのプッシュ時に実行
  workflow_dispatch:  # 手動実行を許可
  • push: 指定したブランチにコードがプッシュされた時に自動実行
  • workflow_dispatch: GitHub の UI から手動でワークフローを実行可能

権限設定の詳細

permissions:
  contents: read    # リポジトリのファイルを読み取る権限
  pages: write     # GitHub Pages への書き込み権限
  id-token: write  # OpenID Connect トークンの発行権限

なぜこれらの権限が必要か？

  • contents: read: OpenAPI ファイルを読み取るため
  • pages: write: 生成したドキュメントを Pages にデプロイするため
  • id-token: write: セキュアな認証プロセスのため

並行実行制御

concurrency:
  group: "pages"
  cancel-in-progress: false
  • 複数のデプロイが同時に実行されることを防ぐ
  • cancel-in-progress: false により、実行中のジョブは完了まで継続

ジョブステップの詳細解説

1. コードのチェックアウト

- name: Checkout code
  uses: actions/checkout@v4
  • リポジトリのコードをランナー環境にダウンロード
  • @v4 は最新の安定版

2. Pages 設定

- name: Setup Pages
  uses: actions/configure-pages@v4
  • GitHub Pages デプロイの準備
  • 必要な環境変数とアクセス権限を設定

3. ドキュメント生成

- name: Generate API Documentation
  run: |
    mkdir -p docs
    npx @redocly/cli build-docs backend/openapi.yaml --output docs/index.html

4. アーティファクトのアップロード

- name: Upload artifact
  uses: actions/upload-pages-artifact@v3
  with:
    path: ./docs
  • 生成されたファイルを GitHub の内部ストレージに一時保存
  • Pages デプロイ用のアーティファクトとして準備

5. GitHub Pages へのデプロイ

- name: Deploy to GitHub Pages
  id: deployment
  uses: actions/deploy-pages@v4
  • Pages 環境にデプロイ
  • id: deployment でデプロイ結果を他のステップから参照可能

設定が正しく完了すると、以下のような URL でドキュメントが公開されます:

https://{username}.github.io/{repository-name}/

Discussion