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

はじめに

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

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

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

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

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

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>

基本的な使い方

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'
      }
    }
  }}
/>