Redocテーマ開発ガイド: カスタムテーマ作成のステップバイステップ

RedocはAPIドキュメント生成ツールとして知られ、デフォルトテーマは基本的なニーズには対応しますが、ブランドスタイルや特定のシナリオに合わせたカスタマイズが必要なケースが多々あります。本ガイドでは、環境構築から最終的なデプロイまで、カスタムテーマの開発プロセスを詳細に解説します。

テーマ開発の基礎

Redocテーマシステム概要

RedocのテーマシステムはTypeScriptで構築されており、`ThemeInterface`というインターフェースを通じて色・レイアウト・フォントなど幅広いカスタマイズが可能です。テーマ設定は主に`src/theme.ts`ファイルで定義され、デフォルトテーマとテーマ解析ロジックを含みます。

システムの核となる`resolveTheme`関数は、テーマ設定内の関数値を処理し、属性の正しい解析を保証します。デフォルトテーマの属性を上書きすることで、個性的な視覚デザインを実現できます。

開発環境構築

テーマ開発を開始する前に、ローカル環境を正しく構築してください。

git clone https://gitcode.com/gh_mirrors/red/redoc.git
cd red/redoc
npm install

開発中はdemoディレクトリのサンプルを使用してリアルタイムプレビューが可能です。

npm run demo

テーマ設定の詳細

テーマ設定ファイル構造

Redocのテーマ設定はネストされたオブジェクト構造を採用し、以下の主要な部分を含みます。

spacing: 要素間の間隔制御
breakpoints: レスポンシブデザインの断点設定
colors: 色設定
typography: レイアウト設定
sidebar: サイドバーのスタイル
logo: ロゴのスタイル
rightPanel: 右パネルのスタイル
codeBlock: コードブロックのスタイル

主要設定項目の解説

色設定

色はテーマカスタマイズで最もよく使用される要素です。

colors: {
  tonalOffset: 0.2,
  primary: {
    main: '#32329f',
    light: ({ colors }) => lighten(colors.tonalOffset, colors.primary.main),
    dark: ({ colors }) => darken(colors.tonalOffset, colors.primary.main),
    contrastText: ({ colors }) => readableColor(colors.primary.main),
  },
  // 他の色設定...
}

`tonalOffset`は色の明暗バリエーションを計算し、この値を調整することですべての色の明暗を統一的に変更できます。

フォント設定

フォント設定はドキュメント全体の読者体験に影響を与えます。

typography: {
  fontSize: '14px',
  lineHeight: '1.5em',
  fontWeightRegular: '400',
  fontWeightBold: '600',
  fontFamily: 'Roboto, sans-serif',
  headings: {
    fontFamily: 'Montserrat, sans-serif',
    fontWeight: '400',
    lineHeight: '1.6em',
  },
  // 他のフォント設定...
}

カスタムフォントを使用する場合、フォントファイルが正しく読み込まれていることを確認し、`fontFamily`に指定してください。

レイアウト設定

レイアウト設定はページ全体の構造に影響を与えます。

sidebar: {
  width: '260px',
  backgroundColor: '#fafafa',
  textColor: '#333333',
  // 他のサイドバー設定...
},
rightPanel: {
  backgroundColor: '#263238',
  width: '40%',
  textColor: '#ffffff',
  // 他の右パネル設定...
}

レスポンシブデザインは`breakpoints`設定を通じて実現されます。

breakpoints: {
  small: '50rem',
  medium: '75rem',
  large: '105rem',
}

カスタムテーマ開発手順

テーマ設定ファイルの作成

プロジェクト内にカスタムテーマファイルを作成します。

import baseTheme from '../theme';

const userDefinedTheme = {
  ...baseTheme,
  colors: {
    ...baseTheme.colors,
    primary: {
      main: '#2c3e50',
      light: '#34495e',
      dark: '#1a2530',
      contrastText: '#ffffff',
    },
    // 他の色変更...
  },
  typography: {
    ...baseTheme.typography,
    fontFamily: 'Arial, sans-serif',
    // 他のフォント変更...
  },
  // 他の設定変更...
};

export default userDefinedTheme;

カスタムテーマの適用

Redocコンポーネントに`theme`プロパティを渡して適用します。

import { RedocStandalone } from '../src';
import userDefinedTheme from '../src/themes/user-defined-theme';

RedocStandalone.init({
  specUrl: 'openapi.yaml',
  theme: userDefinedTheme,
  // 他の設定...
}, document.getElementById('redoc-container'));

リアルタイムプレビューとデバッグ

デモサービスを起動してリアルタイムプレビューを行います。

npm run demo

http://localhost:8080にアクセスすると、カスタムテーマが適用された見た目が確認できます。

高度なテーマカスタマイズ

コンポーネントスタイルの上書き

Redocは`styled-components`を使用しており、コンポーネントのクラス名は通常`rsg-`で始まります。

.rsg--api-info-3 h1 {
  color: #2c3e50;
  font-size: 28px;
}

コンポーネントのカスタマイズ

src/components/ディレクトリにUIコンポーネントが配置されています。

レスポンシブデザインの最適化

メディアクエリを活用した最適化方法。

export const ApiContentWrap = styled.div`
  width: calc(100% - ${props => props.theme.sidebar.width});
  ${media.lessThan('small')`
    width: 100%;
  `};
`;

テーマテストとデプロイ

テーマテストはsrc/**tests**/ディレクトリにテストファイルがあります。

デプロイ方法は以下の3通り:

npmパッケージとして公開
プロジェクトに直接統合
CDN経由での導入

テーマ開発のベストプラクティス

デザインの一貫性を保つ
パフォーマンス最適化（不要な設定の削減、静的値の使用など）
バージョン互換性の確認

無料ダウンロードリンク: https://gitcode.com/gh_mirrors/red/redoc

タグ: TypeScript React styled-components npm

7月25日 22:51 投稿

異端開発室

Redocテーマ開発ガイド: カスタムテーマ作成のステップバイステップ