RedocでAPIドキュメントのバージョンをシームレスに切り替える

Redocは、OpenAPI仕様を魅力的かつインタラクティブなドキュメント形式に変換する強力なAPIドキュメント生成ツールです。特に多バージョン対応のAPIを揃える環境において、** version スイッチ機能 **は、開発者やエンドユーザーが異なるAPIバージョンを直感的に比較・参照・切り替えできる点で不可欠です。

この機能は、UI構成要素と設定の柔軟な設計により実現されており、以下のように主に構成されます。

バージョンドロップダウンの動的レンダリング

Redocでは、バージョン数に応じてUIを動的に調整するコンポーネントが中心的な役割を果たします：

// src/components/ApiVersionSelector/VersionSelector.tsx（仮名）
function ApiVersionSelector({ versions, selected, onChange }: VersionSelectorProps) {
  if (versions.length <= 1) {
    return <span className="static-version">{versions[0]?.name}</span>;
  }

  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
    const url = versions.find(v => v.name === e.target.value)?.url;
    if (url && url !== selected.url) onChange(url);
  };

  return (
    <select
      value={selected.name}
      onChange={handleChange}
      className="version-dropdown"
      aria-label="API Version Selector"
    >
      {versions.map(v => (
        <option key={v.name} value={v.name}>
          {v.current ? `${v.name} (current)` : v.name}
        </option>
      ))}
    </select>
  );
}

この実装では、バージョンが1つしかない場合、静的なラベルとして表示され、UIが混乱しないように考慮されています。一方、複数バージョンが存在する際は、順応性の高いセレクトボックスで操作可能にします。

表示タイトルへのバージョン統合

バージョン情報は、ドキュメントタイトルついての表示領域に自然に埋め込まれます：

// src/components/DocumentHeader/TitleSection.tsx（仮名）
const DocumentTitle = ({ title, version }: { title: string; version?: string }) => (
  <header className="doc-title-section">
    <h1>{title}</h1>
    {version && <span className="version-tag">{version}</span>}
  </header>
);

OpenAPI仕様の info.version を解析し、対応する文字列を動的に挿入することで、どのバージョンを閲覧しているかが一目でわかります。

初期化とバージョン対応の設定

Redocをセットアップする際に、以下のようにバージョン配列を指定することで、ドキュメント切り替え機能を有効化できます：

<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.min.js"></script>
<div id="redoc-root"></div>
<script>
  Redoc.init('https://example.com/spec/v2/openapi.json', {
    specUrls: [
      { name: 'v1', url: 'https://example.com/spec/v1/openapi.json' },
      { name: 'v2 (current)', url: 'https://example.com/spec/v2/openapi.json', current: true },
      { name: 'v3 (preview)', url: 'https://example.com/spec/v3/openapi.json' }
    ],
    scrollYOffset: 60
  }, document.getElementById('redoc-root'));
</script>

この specUrls 配列には、各バージョンに対応するURLと表示名を含めます。current フラグにより、既定で表示されるバージョンを明示的に指定できます。

外観のカスタマイズとブランド統一

Redocのテーマシステムを通じて、セレクトバーの色・フォント・余白などを一括調整することが可能です：

Redoc.init(specUrl, {
  theme: {
    colors: {
      primary: {
        main: '#0052CC',
        dark: '#0040a3'
      },
      text: {
        secondary: '#6B7280'
      }
    },
    typography: {
      fontSize: '15px',
      fontFamily: '"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
      headingFontFamily: '"Inter", sans-serif'
    }
  },
  unifiedRoute: true,
  nativeScrollbars: true
});

これにより、企業のブランドガイドラインに則った表示に調整でき、ドキュメントの一貫性を保ちながら最適な可読性を実現できます。

切り替え時のビュー更新とUX向上

Redocは、バージョン変更時に以下の仕組みでUXの滑らかさを高めています：

  • フェードインアニメーション：新しいドキュメントを読み込む際、既存コンテンツが徐々に消え、新しい内容が淡く現れる。
  • ローディングインジケーター：ネットワーク遅延時に小さなスピンナーを.Iterativeに表示。
  • 可能な限り履歴管理：URL割り当てをhistory.replaceStateで同期し、ブラウザの戻るボタンでもスムーズに切り替えられます。

極端ではありますが、以下のようなカスタム遅延ローディングも可能です：

// サンプル：カスタムローディング画面
function LoadingHarness({ loading }: { loading: boolean }) {
  return (
    <div className={`loader-overlay ${loading ? 'active' : ''}`}>
      <div className="spinner" />
      <span>loading API spec...</span>
    </div>
  );
}

実用シナリオ例

▶ 両バージョンの比較作業（開発・QA向け）

以下のように、左にv1、右にv2の仕様を並列表示（タブ切り替えではなく別画面として）することで差異に気づきやすくなります：

v1 vs v2 comparison

▶ リリースノートとの統合

各バージョンのドキュメントには、専用の"Migration Notes"セクションを設けて、API変更点を箇条書きで展開。Redocの {% include %} 拡張構文を用いて別ファイルを差し込むことで、保守性を高めています。

パフォーマンスと運用における注意点

★ バージョン数が多い場合のパフォーマンス最適化

  • 版本用のJSONをgzip/br圧縮してCDNで配信
  • キャッシングヘッダーをCache-Control: max-age=604800などに設定
  • 遅延読み込み：实际上是使用しないバージョンは、DOM内ではロードしない

例（軽量スケルトン表示）：

<div class="skeleton loader">
  <div class="bar" style="width:60%"></div>
  <div class="bar" style="width:40%"></div>
</div>

.skeleton .bar {
  background: linear-gradient(90deg, #eee, #f5f5f5, #eee);
  animation: loading 1.5s infinite;
}

★ バージョン命名戦略

  • ** <major> 表記**は、v1, v2 などを推奨（簡潔）
  • サブバージョンに対応する場合、例えば v1.1, v1.2-beta
  • 短い識別子でも、READMEやrelease-notes/で長期的な対応情報を提供

安定運用のためのワークフロー推奨

  1. Continuous Integration（CI）ツールで、各バージョンのOpenAPIドキュメント生成と検証を自動化
  2. バージョン選択結果がURLに正しく反映されるか（?version=v2など）を自动化テストで確認
  3. リリース前には、**各バージョンのドキュメント同士における時間的整合性（例：削除されたエンドポイントが履歴に残っていないこと）**をチェック

タグ: redoc OpenAPI SPIバージョン管理 Web API Docs-Tooling

7月10日 17:35 投稿

ホットタグ

©2026 異端開発室