こんにちは！開発の現場で「またAPIの仕様書更新し忘れてるよ…」「古いドキュメント見て実装しちゃったんだけど！」なんて絶叫が聞こえてきた経験はありませんか？
手動でドキュメントを更新するのは、エンジニアにとって最も不毛で、かつバグの温床になりやすい作業です。これを完全に自動化し、コード（API定義）がプッシュされた瞬間に、美しく見やすいドキュメントが勝手にWeb上で更新される仕組み――それが今回構築する「Swagger/OpenAPI × GitHub Actions × GitHub Pages」による完全自動ドキュメントパイプラインです。
これをマスターすれば、ドキュメント作成の苦痛から解放されるだけでなく、チーム全体の開発速度が劇的に跳ね上がりますよ。さあ、一緒にその極意を紐解いていきましょう！
—
1. なぜCI/CDパイプラインでAPIドキュメントを自動生成するのか？
「APIの仕様書は、コードと一緒にGitで管理する」――これは現代の開発における絶対的な正義です。しかし、YAMLやJSONで書かれたOpenAPI（Swagger）の定義書を、そのままステークホルダーに見せるわけにはいきませんよね。人間がパッと見て理解できる「リッチなHTMLドキュメント」に変換し、常に最新の状態を誰でもアクセスできる場所に公開し続ける必要があります。
ここで手動ビルドを持ち出すと、以下のような「人間の限界」にぶつかります。
- 「あ、リリース前にビルドし忘れた」
- 「ローカル環境のNode.jsのバージョン違いでHTMLの見た目が崩れた」
CI/CDに組み込む意義は、「人間のうっかりミス」をシステムで完全にハネ返すことにあります。 「`main` ブランチにマージされたら、自動で綺麗にビルドされて、GitHub Pagesにしれっと反映されている」この状態こそが、プロフェッショナルな開発基盤の証なのです。
—
2. Redocly CLIで美しく圧倒的なHTMLドキュメントをビルドする
APIドキュメントをHTMLに変換するツールはいくつか存在しますが、今選ぶべき最強の選択肢は Redocly CLI です。Swagger UIも悪くありませんが、Redoclyが生成する3ペイン構成（左に目次、中央に詳細、右にコードサンプル）のドキュメントは、圧倒的にモダンで読みやすく、開発者ウケが抜群に良いのです。
まずは、ローカル環境でその実力を体感してみましょう。
プロジェクトの初期セットアップ
適当なディレクトリでプロジェクトを初期化し、OpenAPIの定義ファイル（`openapi.yaml`）と、Redocly CLIを準備します。
プロジェクトの初期化
mkdir api-docs-sample && cd api-docs-sample
npm init -y
Redocly CLIのインストール（ローカル開発用）
npm install -D @redocly/cli
最小限にして完璧な `openapi.yaml`（Hello World的定義）
「Hello World」として、シンプルな「挨拶を返すAPI」の定義を書いてみましょう。プロジェクトのルートに `openapi.yaml` を作成します。
openapi: 3.0.3
info:
title: 魔法の挨拶API
version: 1.0.0
description: |
GitHub Actionsの力で自動生成される、美しきAPIドキュメントのサンプルです。
paths:
/hello:
get:
summary: 挨拶を取得する
description: 世界に向けて愛を込めた挨拶を返します。
responses:
‘200’:
description: 成功時のレスポンス
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: “こんにちは、世界！”
ローカルでのビルド確認
では、この定義書をHTMLにビルドしてみましょう。以下のコマンドを実行してください。
npx @redocly/cli build-docs openapi.yaml -o index.html
これだけで、ディレクトリに `index.html` が生成されます。ブラウザで開いてみてください。驚くほど洗練されたAPIドキュメントが目の前に現れたはずです。「これを毎回のプッシュ時に自動化できたら…」と思いませんか？ 次はその夢を叶えましょう。
—
3. GitHub Actions × GitHub Pages デプロイ設定の全公開
いよいよ本丸です。GitHubのリポジトリにコードがプッシュされたら、自動でRedoclyが動き、GitHub Pagesへデプロイするパイプラインを構築します。
GitHubのプロジェクトルートに、以下のディレクトリとファイルを作成してください。
`.github/workflows/deploy-docs.yml`
YAML設定ファイルの全コード
以下のコードをそのままコピペして使ってください。各行の意図はコメントで詳細に解説しています。
name: Deploy API Documentation
main ブランチにプッシュされた時、または手動で実行したい時に発火
on:
push:
branches:
- main
workflow_dispatch:
GitHub Pagesへのデプロイに必要な権限を設定
permissions:
contents: read
pages: write
id-token: write
同時実行の制御（古いデプロイをキャンセルして最新を優先）
concurrency:
group: “pages”
cancel-in-running: true
jobs:
build-and-deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
# 1. リポジトリのコードをチェックアウト
- name: Checkout repository
uses: actions/checkout@v4
# 2. Node.js環境のセットアップ
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: ’20’
cache: ‘npm’
# 3. 依存パッケージのインストール（package.jsonが存在する場合）
# package.jsonがない場合でも npx を使うため最小限の構成で動きます
- name: Install dependencies
run: |
if [ -f package.json ]; then
npm ci
else
npm install -D @redocly/cli
fi
# 4. Redocly CLIを使って OpenAPI 定義から HTML を生成
# 出力先ファイルを GitHub Pages が認識しやすい index.html に指定
- name: Build Swagger/OpenAPI Documentation
run: |
npx @redocly/cli build-docs openapi.yaml -o index.html
# 5. GitHub Pages用のアーティファクト設定
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# 生成した index.html があるディレクトリを指定
path: ‘.’
# 6. GitHub Pagesへデプロイ実行
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
—
4. GitHubリポジトリ側の最終設定（超重要）
ワークフローファイルをプッシュする前に、GitHub側の設定を1箇所だけ確認しておいてください。ここを忘れるとデプロイでエラー（404など）になります。
1. GitHubの該当リポジトリの Settings（設定）を開く。
2. 左メニューの Pages をクリックする。
3. Build and deployment のセクションにある Source を、従来の `Deploy from a branch` から `GitHub Actions` に変更する。
これだけです！準備が整ったら、`openapi.yaml` と `.github/workflows/deploy-docs.yml` を `main` ブランチにプッシュしてください。
GitHubの「Actions」タブを覗いてみてください。緑色の光の粒が流れるようにビルドが進み、数秒後には世界に向けてあなたのAPIドキュメントが公開されます。
—
最後に：ここから先の実務での応用テクニック
今回はシンプルに単一の `openapi.yaml` から生成しましたが、実務の大きめのAPI開発では、ファイルが肥大化して地獄を見ます。その場合は、`openapi.yaml` を複数のファイル（パスごと、スキーマごとなど）に分割し、Redocly CLIのバンドル機能 (`npx @redocly/cli bundle`) をパイプラインのビルド前に挟むのが王道パターンです。
「仕様が変わったら、プルリクエストを投げるだけで、自動で綺麗なドキュメントが最新化される」
この開発体験を手に入れたチームは、もう手動でのドキュメント管理には絶対に戻れなくなります。
ぜひあなたのプロジェクトにも導入し、快適なAPI開発ライフを満喫してください！