Redoc - OpenAPIから美しいAPIドキュメントを自動生成、これは開発者体験が変わる

はじめに

APIドキュメントの作成、正直なところ面倒くさいですよね。

Swagger UIを使えばそれなりに見れるものはできるんですが、なんというか「見た目がイマイチ」「ナビゲーションが使いにくい」という話をよく聞きます。個人的にもそう感じていました。

そんな悩みを解決してくれるのがRedocです。

RedocはGitHubで25,400スター以上を獲得している、OpenAPI定義から美しいAPIリファレンスドキュメントを自動生成するオープンソースツール。Docker、Zuora、Discourseなど大手企業でも採用されていて、信頼性は折り紙付きです。

10年以上の歴史があって、224人以上のコントリビューターが開発に参加している成熟したプロジェクトですね。

とはいえ、説明を読むより実際に動かしてみた方が早いと思います。ブラウザだけでOpenAPI定義からドキュメントが組み上がる様子を体験できるサンプルを用意したので、先に触ってみたい方はこちらからどうぞ。

＞＞＞まずはサンプルを確認＜＜＜

Redocとは

Redocは、OpenAPI（旧Swagger）の定義ファイルから、見やすく整理されたAPIリファレンスドキュメントを自動生成するツールです。

最大の特徴は3パネルレイアウト。左側にナビゲーションと検索、中央にドキュメント本文、右側にリクエスト/レスポンスのコード例という構成で、情報が整理されていて非常に見やすい。

「一度使ったらSwagger UIに戻れない」という話。これは大げさではなく、実際に使ってみると分かります。

公式サイト: https://redocly.com/redoc GitHub: https://github.com/Redocly/redoc

特徴・メリット

1. 美しい3パネルレイアウト

Redocのドキュメントは見た目が洗練されています。

左パネル: APIナビゲーション、検索機能
中央パネル: エンドポイントの詳細説明、パラメータ、レスポンス仕様
右パネル: リクエスト/レスポンスのJSONサンプル、コード例

レスポンシブデザインにも対応しているので、スマホやタブレットでも崩れません。社内共有や顧客への提供にも使えるクオリティですね。

2. 幅広いOpenAPI仕様への対応

対応している仕様が充実しています。

OpenAPI 3.1
OpenAPI 3.0
Swagger 2.0

最新のOpenAPI 3.1にも対応しているので、JSONスキーマの完全サポートや、webhooks定義なども問題なく表示できます。

3. 複数の導入方法

用途に応じて選べる柔軟性があります。

CLI: コマンド一発で静的HTMLを生成
HTMLタグ: 既存ページに埋め込み可能
Reactコンポーネント: SPAに統合可能

コスパ的に考えると、CLIでの静的HTML生成が一番手軽ですね。CI/CDパイプラインに組み込んで自動化もできます。

4. カスタマイズ性

x-logoやx-tagGroupsなどのベンダー拡張を使って、ロゴの追加やエンドポイントのグルーピングができます。

info:
  x-logo:
    url: "https://example.com/logo.png"
    altText: "Company Logo"

会社のブランディングに合わせたカスタマイズができるのは、業務で使う上で重要なポイントです。

インストール方法

CLIを使う方法（推奨）

Nodeがインストールされている環境なら、npxで即座に使えます。

npx @redocly/cli build-docs openapi.yaml

これだけでredoc-static.htmlが生成されます。時短になりますね。

npmでインストール

プロジェクトに組み込む場合は、npmでインストールします。

npm install @redocly/cli --save-dev

package.jsonのscriptsに追加しておくと便利です。

{
  "scripts": {
    "docs": "redocly build-docs openapi.yaml -o docs/api.html"
  }
}

CDNから読み込む

既存のHTMLに組み込むなら、CDNが手軽です。

<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
  <meta charset="utf-8"/>
  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
  <redoc spec-url="./openapi.yaml"></redoc>
  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

Redocのサンプルを動かす

Redocの核となるAPIは、Redoc.init(spec, options, element)というグローバル関数1つです。第1引数にOpenAPI定義のオブジェクト（またはURL）、第2引数に表示オプション、第3引数に描画先のDOM要素を渡すだけで、ブラウザ内だけでAPIリファレンスドキュメントが組み立てられます。ここではspec-urlで外部ファイルを指定する代わりに、OpenAPI定義をJavaScriptオブジェクトとしてそのまま渡すパターンで動かしてみます。

要点だけを抜き出すと、次のようになります。

// Redoc.init(spec, options, container) の3引数だけで描画できる
const spec = {
  openapi: '3.0.3',
  info: { title: 'Task API', version: '1.0.0' },
  paths: {
    '/tasks': {
      get: {
        summary: 'タスク一覧を取得',
        responses: {
          '200': { description: '成功' }
        }
      }
    }
  }
}

Redoc.init(spec, {}, document.getElementById('redoc-container'))

実際に動かせるのが下のサンプルです。左のナビゲーションからGET /tasksやPOST /tasksをクリックすると、中央パネルにパラメータ・スキーマの説明、右パネルにレスポンス例が表示される、Redoc特有の3パネルレイアウトを確認できます。specオブジェクト内のsummaryやdescriptionの文字列を書き換えると、ドキュメントの表示内容がそのまま変わります。

このようにRedoc.init()はOpenAPI定義さえ渡せば動くので、CIで生成したJSONをそのままフロントエンドに埋め込むといった使い方もできます。次は、同じRedoc.init()の第2引数（options）を差し替えて、テーマとレイアウトを動的に変えるパターンを見てみましょう。

テーマとレイアウトをoptionsで切り替える

Redocのoptions引数では、themeでカラーパレットやサイドバーの配色を変更できるほか、pathInMiddlePanelでエンドポイントのパスをサイドバーではなく中央パネルに表示したりと、見た目だけでなくレイアウトそのものも制御できます。

// options引数だけを差し替えて再描画すれば、テーマとレイアウトが変わる
const darkTheme = {
  theme: {
    colors: { primary: { main: '#f97316' } },
    sidebar: { backgroundColor: '#1a1a2e', textColor: '#ffffff' }
  },
  pathInMiddlePanel: true // パスをサイドバーではなく中央パネルに表示する
}

Redoc.init(spec, darkTheme, document.getElementById('redoc-container'))

下のサンプルでは、ボタンで「ライト / ブルー」「ダーク / オレンジ」の2テーマを切り替えられるほか、チェックボックスでpathInMiddlePanelのON/OFFを切り替えられます。チェックを入れるとサイドバーからパスの文字列が消え、中央パネルの見出し部分に移動する様子が確認できるはずです。

themeとpathInMiddlePanelは、Redoc.init()の第2引数に渡せるオプションのごく一部です。ほかにもhideDownloadButton（ダウンロードボタンの非表示）やdisableSearch（検索ボックスの非表示）、expandResponses（レスポンス例の初期展開）など、見た目や挙動を細かく制御できるオプションが用意されているので、自社サイトに埋め込む際は公式ドキュメントのオプション一覧を参照しながら調整するとよいでしょう。

基本的な使い方

1. OpenAPI定義ファイルを用意

まずはOpenAPI形式のYAMLまたはJSONファイルを用意します。

openapi: 3.0.3
info:
  title: Sample API
  description: サンプルAPIのドキュメント
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: ユーザー一覧取得
      description: 登録されているユーザーの一覧を取得します
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: ユーザーID
        name:
          type: string
          description: ユーザー名
        email:
          type: string
          format: email
          description: メールアドレス

2. ドキュメントを生成

CLIでHTMLを生成します。

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

オプションで出力ファイル名を指定できます。

3. 開発中のプレビュー

リアルタイムプレビューも可能です。

npx @redocly/cli preview-docs openapi.yaml

ブラウザでhttp://localhost:8080にアクセスすると、変更を即座に確認できます。開発中はこれが便利ですね。

4. Reactコンポーネントとして使用

SPAに組み込む場合は、Reactコンポーネントとして使えます。

npm install redoc

import { RedocStandalone } from 'redoc';

function ApiDocs() {
  return (
    <RedocStandalone
      specUrl="./openapi.yaml"
      options={{
        theme: {
          colors: {
            primary: { main: '#1976d2' }
          }
        },
        hideDownloadButton: false,
        expandResponses: '200,201'
      }}
    />
  );
}

export default ApiDocs;

実践的なユースケース

1. CI/CDでの自動ドキュメント生成

GitHub Actionsでの自動化例です。

name: Generate API Docs

on:
  push:
    paths:
      - 'openapi.yaml'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx @redocly/cli build-docs openapi.yaml -o docs/index.html
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

OpenAPI定義を更新するたびに、自動的にドキュメントがデプロイされる仕組みです。QOL上がりますね。

2. 複数API仕様の統合

大規模なプロジェクトでは、複数のOpenAPIファイルを管理することがあります。

# redocly.yaml
apis:
  user-api:
    root: ./specs/user-api.yaml
  order-api:
    root: ./specs/order-api.yaml

Redocly CLIの設定ファイルを使えば、複数APIを一元管理できます。

3. カスタムテーマの適用

ブランドカラーに合わせたカスタマイズも可能です。

<RedocStandalone
  specUrl="./openapi.yaml"
  options={{
    theme: {
      colors: {
        primary: { main: '#FF6B6B' },
        success: { main: '#4CAF50' },
        error: { main: '#F44336' }
      },
      typography: {
        fontSize: '16px',
        fontFamily: '"Noto Sans JP", sans-serif',
        headings: {
          fontFamily: '"Noto Sans JP", sans-serif'
        }
      },
      sidebar: {
        backgroundColor: '#1a1a2e',
        textColor: '#ffffff'
      }
    }
  }}
/>