Scalar API リファレンス Nuxt モジュール

このプラグインは、Nuxt で OpenAPI/Swagger ファイルに基づいて美しい API リファレンスをレンダリングする簡単な方法を提供します。

クイックセットアップ

次のコマンドでモジュールを Nuxt アプリケーションにインストールします。

npx nuxi module add @scalar/nuxt

これで完了です！Nuxt アプリで @scalar/nuxt を使用できるようになりました✨

構成

nuxt サーバールートを使用している場合は、nuxt.config.ts の nitro config で openAPI を有効にするだけで、scalar を有効にできます。

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  nitro: {
    experimental: {
      openAPI: true,
    },
  },
})

独自の OpenAPI 仕様ファイルを追加したい場合は、次の最小限の構成で行うことができます。

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    spec: {
      url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
    },
  },
})

デフォルトでは、ドキュメントは /docs でホストされますが、簡単にカスタマイズできます。詳細な構成例を以下に示します。

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    darkMode: true,
    hideModals: false,
    hideDownloadButton: false,
    metaData: {
      title: 'API Documentation by Scalar',
    },
    proxy: 'https://proxy.scalar.com',
    searchHotKey: 'k',
    showSidebar: true,
    pathRouting: {
      basePath: '/scalar',
    },
    spec: {
      url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
    },
  },
})

複数のリファレンスについては、基本構成の上位に拡張される構成オブジェクトの配列を渡します。

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    darkMode: true,
    metaData: {
      title: 'API Documentation by Scalar',
    },
    proxy: 'https://proxy.scalar.com',
    configurations: [
      {
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml,
        },
        pathRouting: {
          basePath: '/yaml',
        },
      },
      {
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
        },
        pathRouting: {
          basePath: '/json',
        },
      },
    ],
  },
})

テーマ構成については、構成オブジェクトに theme プロパティを渡すことができます。デフォルトのテーマは nuxt ですが、default を渡してデフォルトのテーマを使用することもできます。

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    theme: 'nuxt',
  },
})

トラブルシューティング

**** not default export エラーが発生した場合は、pnpm を使用している可能性が高いです。この一時的な修正としては、パッケージの問題の原因を解決するまで、shamefully-hoist を有効にすることが挙げられます。

これを実行するには、プロジェクトのルートに .npmrc ファイルを作成し、次のように記述します。

shamefully-hoist=true