scalar-api-reference

Scalar API リファレンス

フレームワークに合ったインテグレーションを使って、既存のアプリケーションにインタラクティブな API ドキュメントを追加できます。Scalar は API 定義を表示します。アプリケーションで既に使用している定義ジェネレーターと API ルートはそのまま維持してください。

インテグレーションを選択する

アプリケーションのフレームワーク、パッケージのバージョン、ルーティングの規則、既存の API 定義エンドポイントを確認します。スタンドアロンのドキュメントルートが必要か、アプリケーションのレイアウトに埋め込むコンポーネントが必要かを判断してください。

フレームワークインテグレーションの該当項目を読み、そのインテグレーション固有のオプションについては、リンク先のガイドを参照してください。プロジェクトで使用しているパッケージマネージャーを使います。すべてのラッパーが同じオプション名を受け付けると決めつけず、インストールされているバージョンのエクスポートと型に合わせてください。

通常の HTML ページの場合、最小限の構成は次のとおりです。/openapi.json で API 定義を配信し、ページを HTTP 経由で配信してください。

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>API Reference</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module">
      import { createApiReference } from 'https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js'

      createApiReference('#app', { url: '/openapi.json' })
    </script>
  </body>
</html>

バンドラーを使う JavaScript では、@scalar/api-reference から createApiReference をインポートします。Vue および React コンポーネントでは、Vue と React のスタイルに示すように、インテグレーションのスタイルシートを含めてください。

フレームワークインテグレーション

アプリケーションのフレームワークに対応するガイドだけを読んでください。これらはルーティングのヒントと最小限の導入例であり、インストール済みパッケージの API に代わるものではありません。ローカルソースが利用可能な場合、リンク先のガイドは Scalar リポジトリ内の documentation/integrations/ にあります。

アプリケーション	パッケージ	エントリーポイントとガイド
HTML またはバニラ JavaScript	@scalar/api-reference	createApiReference('#app', { url })；HTML/JS
Vue	@scalar/api-reference	configuration プロパティを指定した ApiReference コンポーネント；Vue
React	@scalar/api-reference-react	configuration プロパティを指定した ApiReferenceReact；React
Next.js スタンドアロンルート	@scalar/nextjs-api-reference	ルートハンドラーを返す ApiReference；Next.js
Nuxt	@scalar/nuxt	scalar 設定を使用する Nuxt モジュール；Nuxt
Express	@scalar/express-api-reference	app.use('/reference', apiReference({ url }))；Express
Fastify	@scalar/fastify-api-reference	routePrefix とネストされた configuration を指定してプラグインを登録；Fastify
Hono	@scalar/hono-api-reference	app.get('/scalar', Scalar({ url }))；Hono
NestJS	@scalar/nestjs-api-reference	既存の SwaggerModule の出力とともに apiReference({ content: document }) を使用；NestJS
FastAPI	scalar-fastapi	add_scalar_reference(app) または get_scalar_api_reference；FastAPI
ASP.NET Core	Scalar.AspNetCore	OpenAPI ドキュメントのエンドポイントと併せて app.MapScalarApiReference() を使用；ASP.NET Core

その他のフレームワークについては、インテグレーションカタログで該当するガイドを探してください。フレームワークのサポートを確認せずに、名前が似ているパッケージで代用しないでください。

Vue と React のスタイル

Vue：

<script setup lang="ts">
import { ApiReference } from '@scalar/api-reference'
import '@scalar/api-reference/style.css'
</script>

<template>
  <ApiReference :configuration="{ url: '/openapi.json' }" />
</template>

React：

import { ApiReferenceReact } from '@scalar/api-reference-react'
import '@scalar/api-reference-react/style.css'

export const Reference = () => (
  <ApiReferenceReact configuration={{ url: '/openapi.json' }} />
)

Next.js：ルートまたはページを選択する

スタンドアロンの HTML ドキュメントを作成するには、app/scalar/route.ts（アプリケーションで src/ を使用している場合はその下）を作成します。

import { ApiReference } from '@scalar/nextjs-api-reference'

export const GET = ApiReference({ url: '/openapi.json' })

これはアプリケーションのレイアウトや React プロバイダーを継承しません。ページに埋め込む場合は、'use client' を指定した Client Component で React コンポーネントを使用し、ページからインポートします。ブラウザーのコールバックは、その Client Component 内で定義します。同じルートに page.tsx と route.ts の両方を作成しないでください。メタデータ、CSP、レンダラーのバージョン固定については、Next.js ガイドを参照してください。

サーバー統合における違い

• Fastify では、共通オプションは configuration の下にネストされます。@fastify/swagger がすでに登録されている場合、明示的な content または url が指定されていなければ、生成された定義を使用できます。
• NestJS では、UI を置き換えたまま SwaggerModule.createDocument を使用できます。Fastify アダプターの場合は、withFastify オプションを確認してください。
• FastAPI の Python ラッパーでは、openapi_url、scalar_proxy_url、custom_css などの名前が使われます。JavaScript のオプション名を Python のキーワード引数にそのまま貼り付けないでください。add_scalar_reference(app) は既定で /scalar を登録し、アプリの OpenAPI URL を読み取ります。
• ASP.NET Core では、独自の Fluent Configuration API を使用します。JavaScript のオプションを置き換える前に、プロジェクトの .NET バージョンとドキュメントジェネレーターに対応したガイドを確認してください。

API 定義を読み込む

オプションの正確な形式については、設定リファレンスを使用してください。

• url：JSON または YAML を提供する、ブラウザーからアクセス可能な URL です。ファイルシステムのパスや HTML ドキュメントページではありません。
• content：アプリケーションですでに利用可能な API 定義オブジェクト、または JSON／YAML 文字列です。
• sources：title、slug、default による選択を任意で指定できる、複数の API 定義です。各ソースには url または content を選択してください。

たとえば、共通の JavaScript 設定では、2 つの API を選択できます。

{
  sources: [
    { title: 'Public API', slug: 'public', url: '/openapi.json', default: true },
    { title: 'Admin API', slug: 'admin', url: '/admin/openapi.json' },
  ],
}

ブラウザーがドキュメントページの URL を基準に定義 URL をどのように解決するか確認してください。先頭にスラッシュがある場合はオリジンのルートが使用され、ないパスはページからの相対パスになるため、デプロイ時のベースパスを考慮してください。ドキュメントのエンドポイントが、ログインページや SPA のフォールバックではなく API 定義を返すことを確認してください。content を渡すと、その定義がブラウザーに送信される内容に含まれます。

認証とテストリクエスト

ドキュメントページへのアクセス、API 定義へのアクセス、API リクエストの認証を区別してください。リクエストクライアントの認証を設定しても、ページや定義のエンドポイントは保護されません。

authentication.preferredSecurityScheme と authentication.securitySchemes を設定する際は、API 定義のセキュリティスキームキーを使用してください。該当する HTTP、API キー、OAuth フローについては設定リファレンスを確認し、汎用的な apiKey オプションを作り出さないでください。製品に同梱するブラウザー設定に、本番環境のシークレットを含めないでください。要求がある場合にのみ persistAuth を有効にしてください。これは認証情報をブラウザーのローカルストレージに保存します。

リクエストが失敗した場合は、選択されたサーバー URL、リクエスト URL、ヘッダー、ステータス、ブラウザーのコンソールを調べてください。リファレンスがレンダリングされたからといって、API リクエストが機能するとは限りません。API 本来の CORS 設定を優先し、デプロイ環境に適している場合は proxyUrl を設定してください。リクエストと認証情報はそのプロキシを経由するため、既存のアプリケーションに公開プロキシを黙って追加しないでください。

外観とコードサンプル

まず、サポートされている設定（theme、layout（modern または classic）、showSidebar、darkMode）から始めます。ブランディングには、内部 DOM セレクターに依存するのではなく、テーマ変数または customCss を使用してください。埋め込みリファレンスでは、Tailwind のスタイルが競合する場合、テーマガイドで CSS レイヤーの順序を確認してください。

defaultHttpClient に targetKey と clientKey を指定して初期コードサンプルを選び、hiddenClients で利用可能なクライアントを制限します。サポートされている値と形式については、設定リファレンスを参照してください。これらの設定で変わるのはコードサンプルの選択であり、API のサーバー実装ではありません。

Swagger UI または Redoc からの移行

既存の API 定義 URL またはジェネレーターの出力を再利用します。目的のルートでドキュメントレンダラーを置き換え、ユーザーが必要とするカスタマイズだけを移行します。Swagger UI と Redoc のオプション名は、Scalar のオプション名と互換性がありません。

定義の生成、ルートの認可、サーバー URL はそのまま維持します。古いレンダラーの依存関係は、ほかで使用されていないことを確認してから削除してください。ドキュメント自体を変更する必要がある場合は、レンダラーを切り替えるだけの理由でアップグレードするのではなく、宣言されている OpenAPI バージョンに従ってください。

検証とトラブルシューティング

ドキュメントのルートと定義エンドポイントを個別に確認します。レンダリングされたリファレンスで、オペレーションが表示されること、検索で既知のオペレーションが見つかること、指定したテーマや認証の設定が反映されていることを検証してください。リクエストのテストが対象に含まれる場合は、安全性が確認されたエンドポイントまたはモック環境を使用します。

• ページが空白、またはスタイルが適用されない場合：ブラウザーのエラー、マウント要素、コンポーネントの CSS インポート、レンダラーがブラウザーのコンテキストで実行されているかを確認します。
• 定義の読み込みに失敗する場合：フェッチの応答、URL、アクセス制御、CORS、解決されていない外部参照を調べます。
• リクエストの送信先ホストが誤っている場合：定義の servers と、設定済みのサーバー上書きを調べます。
• CSP によって初期化がブロックされる場合：フレームワークガイドの nonce とバンドルに関するガイダンスを参照してください。サンプルを動作させるために、アプリケーションのポリシーを広範に緩和してはいけません。
• CDN の動作がインストール済みラッパーと異なる場合：ラッパーとブラウザーレンダラーでは、別々のバージョンが使われていることがあります。バージョンの固定が必要な場合は、統合ガイドの bundle または cdn を確認してください。

ホストアプリケーションに関連するチェックを実行します。検証した内容と環境上の制約を報告してください。コンパイルだけを根拠に、ブラウザーでの動作をテストしたと主張してはいけません。