企业官网建设流程全解析

在 Next.js 中集成 Scalar API Reference：从快速开始到生产级配置

【免费下载链接】scalarScalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar

本指南讲解如何在 Next.js 项目中通过@scalar/nextjs-api-reference包，以 App Router 路由处理器（Route Handler）的方式托管交互式 API 文档。你将掌握从安装、挂载 OpenAPI/Swagger 描述文件，到配置 CDN、页面标题、CSP nonce 以及自定义主题的完整流程，并理解该集成的底层渲染机制与测试验证方式。

概述：Scalar 与 Next.js 的集成方式

Scalar 是开源的 API 平台，核心能力之一是基于 OpenAPI/Swagger 描述文件生成美观、可交互的 API 参考文档。@scalar/nextjs-api-reference是 Scalar 针对 Next.js 官方提供的适配器（adapter），它把文档渲染能力封装成一个 Next.jsAPI Route Handler：你只需把 OpenAPI 描述文件放进项目，写一个几行的路由文件，就能在/scalar等路径下获得一份完整的、支持搜索、请求调试的 API 文档页面。

从实现结构看，该集成位于 integrations/nextjs 目录，核心代码量很小但职责清晰：

• src/ApiReference.ts：提供ApiReference工厂函数，返回一个标准的 Next.js 路由处理器；
• src/types.ts：定义配置类型；
• src/custom-theme.ts：内置的默认主题 CSS。

快速开始

安装依赖

在 Next.js 项目根目录安装集成包：

npm install @scalar/nextjs-api-reference

从 package.json 可以确认该包的版本要求：peerDependencies声明支持 Next.js^15.0.0 || ^16.0.0与 React^19.0.0，同时要求 Node.js 版本>=22，使用时请确保环境满足这些约束。

放置 OpenAPI 描述文件

将你的 OpenAPI 描述文件放在 Next.js 的静态资源目录：

public/openapi.json

这样文件可以通过/openapi.json路径直接访问。除了 JSON 文件，OpenAPI 描述也可以由服务端动态生成（后文会介绍用 Route Handler 提供描述的方案）。

创建 API Reference 路由

在 App Router 下新建一个路由文件：

// app/scalar/route.ts import { ApiReference } from '@scalar/nextjs-api-reference' export const GET = ApiReference({ url: '/openapi.json' })

启动开发服务器后访问/scalar，即可看到交互式 API 文档页面。

在应用布局中嵌入（App Router）

以上方式是将文档托管在独立路由下。若希望把 Scalar 文档嵌入到应用的某个页面布局中（而不是独立页面），可以参考本仓库 examples/nextjs-api-reference 中提供的完整可运行示例工程，其中展示了结合 App Router 在页面中渲染 API 参考文档的完整配置（next.config.mjs、页面组件与样式等）。该示例也是验证本集成在实际 Next.js 工程中运行效果的最直接参考。

配置项详解：ApiReference的参数

ApiReference接收一个配置对象，返回类型为() => Response的路由处理器。配置类型ApiReferenceConfiguration直接继承自@scalar/client-side-rendering包中的HtmlRenderingConfiguration（见 src/types.ts），因此所有 HTML 渲染相关配置项都可用。下面结合源码与实际用例说明常用配置：

默认配置与合并逻辑

从 src/ApiReference.ts 的源码可以看到，集成层在创建路由处理器时会把默认配置与你传入的配置合并：

const DEFAULT_CONFIGURATION: Partial<ApiReferenceConfiguration> = { _integration: 'nextjs', } export const ApiReference = (givenConfiguration: Partial<ApiReferenceConfiguration>): (() => Response) => { const configuration: Partial<ApiReferenceConfiguration> = { ...DEFAULT_CONFIGURATION, ...givenConfiguration, } // ... }

即：无论你是否传入，_integration: 'nextjs'都会被自动注入；而你传入的配置项（如title、url）会覆盖默认值。这一点在 test/ApiReference.test.ts 的单元测试中有明确验证——测试断言renderApiReference收到的配置objectContaining({ title: 'Test API', _integration: 'nextjs' })，证明默认配置确实与用户配置发生了合并。

底层渲染机制

ApiReference返回的路由处理器内部并不直接拼接 HTML，而是调用@scalar/client-side-rendering包的renderApiReference函数（定义于 packages/client-side-rendering/src/html-rendering.ts）完成服务端渲染，随后包装为标准Response：

return () => { const { cdn, pageTitle, nonce, ...config } = configuration const referenceDocument = renderApiReference({ config, pageTitle, cdn, nonce }, customTheme) return new Response(referenceDocument, { status: 200, headers: { 'Content-Type': 'text/html' }, }) }

这里有几个值得注意的细节：

• cdn、pageTitle、nonce三个字段会被从config中解构出来，单独传给渲染函数，而不是混入config对象；
• 渲染结果以text/html的Content-Type返回，状态码恒为200；
• 每次请求都会执行一次渲染，因此天然支持按请求动态生成 nonce（见下文 CSP 一节）。

这也解释了为什么该集成的测试（test/ApiReference.test.ts）会断言：ApiReference({})返回一个函数、调用后返回Response实例、status === 200、Content-Type为text/html。

内置默认主题

集成层自带一份默认主题 CSS，定义在 src/custom-theme.ts，覆盖了：

• 深色模式（.dark-mode）与浅色模式（.light-mode）下的基础色板，包括文字颜色（--scalar-color-1/2/3）、强调色--scalar-color-accent: #3070ec、背景色（--scalar-background-1/2/3）与边框色；
• 文档头部（.t-doc__header）的半透明背景与毛玻璃效果（backdrop-filter: saturate(180%) blur(5px)）；
• 侧边栏（.t-doc__sidebar）的悬停、选中状态与缩进线颜色；
• 按钮、语法高亮色（绿/红/黄/蓝/橙/紫）、滚动条等高级样式变量。

若需自定义主题，可通过 Scalar 的 CSS 变量体系覆盖这些变量。完整的配置项说明可参阅仓库内的 documentation/configuration.md。

生产环境进阶：CSP 与动态 OpenAPI 描述

集成包内置了对内容安全策略（CSP）的支持。根据 CHANGELOG.md（0.11.0版本）的说明：传入nonce后，渲染出的 HTML 会把它打在内联<script>、CDN<script>、Scalar 自身的<style>标签以及对应的<meta property="csp-nonce">上，使 API Reference 能在严格的script-src策略（不开启unsafe-inline、unsafe-eval）下正常运行。

本仓库的 Playwright 端到端测试夹具给出了一个完整的生产级用法（playwright/fixture/app/scalar/route.ts）：

import { ApiReference } from '@scalar/nextjs-api-reference' export const GET = (request: Request): Response => { const nonce = new URL(request.url).searchParams.has('csp') ? crypto.randomUUID() : undefined const response = ApiReference({ url: '/openapi.json', pageTitle: 'Next.js compatibility', cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.67.0', nonce, })() if (nonce) { response.headers.set( 'Content-Security-Policy', `script-src 'nonce-${nonce}'; style-src 'unsafe-inline' https:; font-src https: data:; img-src https: data:`, ) } return response }

该模式展示了三个要点：

1. 每次请求生成新 nonce：crypto.randomUUID()保证每次请求的 nonce 都不同。对应的端到端测试（playwright/test/reference.spec.ts）专门验证了这一点——两次请求的 CSP 头内容不同，且 HTML 中的nonce="..."与响应头中的 nonce 一致；
2. CDN 固定版本：将cdn固定到明确的发布版本（@scalar/api-reference@1.67.0），避免资源内容漂移；
3. 动态设置 CSP 响应头：在 handler 内对响应头进行后处理，把 nonce 写入Content-Security-Policy。

同时，OpenAPI 描述文件本身也可以由 Route Handler 动态生成。测试夹具 playwright/fixture/app/openapi.json/route.ts 展示了如何通过Response.json(...)返回一个内存中的 OpenAPI 3.1 文档（含info与paths），从而在不依赖任何外部 API 描述服务的情况下完成端到端验证：

export const GET = (): Response => Response.json({ openapi: '3.1.0', info: { title: 'Compatibility API', version: '1.0.0' }, paths: {}, })

测试与验证：集成如何被保障

该集成配备了双层测试，可作为你在自己项目中接入时的验证模板：

• 单元测试（test/ApiReference.test.ts，基于 Vitest）：mock 掉@scalar/client-side-rendering，验证ApiReference返回函数、Response 结构（状态码、Content-Type、正文）、默认配置合并以及传给renderApiReference的参数；
• 端到端测试（playwright/test/reference.spec.ts，基于 Playwright）：在真实 Next.js 生产服务器中分别访问/scalar与/scalar?csp，断言页面标题为Next.js compatibility、文档标题Compatibility API可见、页面无 JS 报错、OpenAPI 描述只被请求一次（descriptionRequests === 1），并验证 CSP nonce 每次请求都会重新生成。

这两个测试文件放在包内test与playwright目录，可直接在本地通过pnpm test（运行单元测试）执行验证。

小结

@scalar/nextjs-api-reference以极小的接入成本（一个依赖、一个路由文件）为 Next.js 项目提供了完整的交互式 API 文档能力。其核心设计是：ApiReference(config)将配置与默认值合并后，委托@scalar/client-side-rendering的renderApiReference在服务端渲染 HTML，并以Response返回，同时通过cdn、pageTitle、nonce等参数兼顾了 CDN 分发、页面元信息与严格 CSP 等生产需求。结合仓库内的源码、测试夹具与 examples/nextjs-api-reference 示例工程，你可以快速将其落地到自己的 Next.js 应用中。

【免费下载链接】scalarScalar is an open-source API platform: 🌐 Modern REST API Client 📖 Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar