Scalar API 參考 Nuxt 模組

此插件提供一種簡單的方式，使用 Nuxt 根據 OpenAPI/Swagger 檔案渲染美觀的 API 參考。

快速設定

使用一個命令將模組安裝到您的 Nuxt 應用程式中

npx nuxi module add @scalar/nuxt

就這樣！您現在可以在您的 Nuxt 應用程式中使用 @scalar/nuxt ✨

組態設定

如果您使用 Nuxt 伺服器路由，您只需在 nuxt.config.ts 中的 nitro 設定中啟用 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',
    },
    proxyUrl: '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',
    },
    proxyUrl: '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