1. 導入: なぜ今、Redocが選ばれるのか
API開発において、Swagger UIは定番のツールですが、仕様が巨大化すると「どこに何があるか分からない」「ページが重い」といった課題に直面しがちです。Redocは、OpenAPI定義から「3カラム構成」の静的HTMLを生成するツールで、左側に目次、中央に詳細、右側にコード例を表示するため、情報の視認性が非常に高いのが特徴です。開発体験（DX）を向上させ、外部パートナーやフロントエンドチームへの共有を円滑にするために、今多くの現場でRedocが採用されています。
2. 基礎知識: Redocとは何か
Redocは、OpenAPI（旧Swagger）仕様書をブラウザ上で美しくレンダリングするためのオープンソースツールです。静的ファイルを生成できるため、S3やGitHub Pagesでホスティングでき、バックエンドサーバーを立てる必要がないのが強みです。
・OpenAPI: APIの仕様を定義するフォーマット（YAML/JSON）。
・3カラム構成: 画面を3分割し、ナビゲーション・詳細・サンプルコードを同時表示するレイアウト。
・静的サイト生成: 動的なサーバー処理を介さないため、高速かつセキュアです。
3. 実装/解決策: Redoc CLIによるHTML生成
最も手軽な方法は、Redoc CLIを使用して、OpenAPI定義ファイルを単一のHTMLファイルに変換する方法です。これにより、特別なインフラを用意することなく、配布可能なドキュメントを作成できます。
4. サンプルプログラム: Redoc CLIを用いたビルドスクリプト
まずはNode.js環境でRedoc CLIをインストールし、以下の手順でHTMLを出力します。
1. Redoc CLIのインストール
npm install -g redoc-cli
2. build.sh (ビルド用スクリプト例)
!/bin/bash
OpenAPIのYAMLファイルを指定し、静的なHTMLを生成する
–output: 出力先のファイル名
–title: HTMLのタイトルタグ設定
–options.hideDownloadButton: ダウンロードボタンの非表示（必要に応じて）
redoc-cli bundle openapi.yaml -o index.html –title “API仕様書 – v1.0.0”
echo “ドキュメントの生成が完了しました: index.html”
3. HTMLファイル内で直接表示する場合のテンプレート例
5. 応用・注意点: 現場での運用のコツ
・CI/CDへの組み込み: GitHub Actionsと連携し、リポジトリにYAMLをプッシュしたタイミングで自動的にHTMLを生成し、GitHub Pagesへデプロイする運用が推奨されます。
・検索機能の活用: Redocには標準で強力な検索機能が備わっています。大規模APIの場合は、タグ付け（tags）を適切に行うことで、より検索性の高いドキュメントになります。
・陥りやすい罠: OpenAPI定義ファイルに記述ミスがあると、Redoc側でレンダリングエラーになります。CIプロセスの中に「Spectral」などのLintツールを組み込み、ビルド前に定義ファイルの妥当性をチェックする仕組みを必ず作りましょう。これだけで、ドキュメントの品質が劇的に安定します。