在 Next.js 中接入 Scalar API Referencescalar/nextjs-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/scalarscalar/nextjs-api-reference是 Scalar 官方为 Next.js 提供的 API 文档渲染集成包只需几行代码就能把一个 OpenAPI/Swagger 文档渲染成开箱即用的交互式 API Reference 页面。本文以该包的 CHANGELOG 为主线结合仓库中的 README、源码与测试系统讲解它的安装接入、核心配置含 CSPnonce、破坏性变更时间线以及底层实现原理帮助你既会用、又能理解它为什么这样设计并为升级迁移提供明确依据。包定位一个返回 Route Handler 的 Next.js 适配器scalar/nextjs-api-reference的自我定位是一段 Next.js API route handler to serve beautiful, interactive API documentation from OpenAPI/Swagger documents见 integrations/nextjs/package.json。它不直接渲染组件而是提供一个工厂函数ApiReference(config)返回一个同步的 Route Handler 函数由 Next.js 的路由系统调用后输出完整的 HTML 页面。这一设计在 0.9.0 版本中正式定型makeApiReferencereturn a synchronous route handler见 CHANGELOG。而最早在 0.1.1 版本中这个适配器就已经从组件改造成了 API Route 形态changelog 原话moved next.js adapter to an api route并同步放开了对 Next.js 14 的支持。快速上手App Router 三步接入按照 integrations/nextjs/README.md 的 Quickstart接入过程非常简单npm install scalar/nextjs-api-reference把你的 OpenAPI 描述文件放到public/openapi.json然后创建一个路由文件// app/scalar/route.ts import { ApiReference } from scalar/nextjs-api-reference export const GET ApiReference({ url: /openapi.json })启动应用后访问/scalar即可看到渲染完成的 API Reference 页面。这个模式适用于 Next.js App RouterPages Router 的使用方式也在 0.4.0 版本中随文档一起补充过见 changelog docs for next.js pages router。核心配置项url/content/pageTitle/cdn/nonceApiReference接收的配置对象类型为ApiReferenceConfiguration它直接复用了scalar/client-side-rendering包中的HtmlRenderingConfiguration类型见 integrations/nextjs/src/types.ts。也就是说所有 HTML 渲染层面的配置项在 Next.js 集成中都可用。0.7.0 破坏性变更spec前缀被移除在 0.7.0 之前文档地址需要通过spec.url/spec.content这样的嵌套对象传入。0.7.0 版本做了破坏性变更remove the spec prefix, makecontentandurltop-level attributes见 CHANGELOG从此以后配置扁平化为顶层属性// 0.7.0 之后的标准写法 ApiReference({ url: /openapi.json, // 指向一个 OpenAPI 文档地址 // 或者直接内联文档内容 // content: { openapi: 3.1.0, info: {...}, paths: {...} }, })其中url支持的能力在 0.4.12 版本add URL support引入content则用于直接内联 OpenAPI 对象。两者取其一即可也是当前 README 示例所用的写法。pageTitle、cdn与_integration默认值在 integrations/nextjs/src/ApiReference.ts 的源码中可以看到ApiReference会先合并一组默认配置再调用底层的renderApiReferenceimport { renderApiReference } from scalar/client-side-rendering import { customTheme } from ./custom-theme import type { ApiReferenceConfiguration } from ./types const DEFAULT_CONFIGURATION: PartialApiReferenceConfiguration { _integration: nextjs, } export const ApiReference (givenConfiguration: PartialApiReferenceConfiguration): (() Response) { const configuration: PartialApiReferenceConfiguration { ...DEFAULT_CONFIGURATION, ...givenConfiguration, } 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 }, }) } }要点如下_integration: nextjs包内部默认注入的框架标识符用于调试与统计分析对应 0.4.96 版本的 add framework identifier for debugging purposes。用户传入的配置会覆盖该默认值。pageTitle页面title的取值底层默认为Scalar API Reference见 packages/client-side-rendering/src/html-rendering.ts。cdnCDN 上 standalone bundle 的地址默认使用 jsDelivr。0.4.93 版本明确pin cdn version in integrations即集成层默认锁定具体版本避免漂移。nonceCSP 支持选项详见下一节。bundle加载构建产物模式的选项true/ URL /false0.11.x 起由scalar/client-side-rendering统一提供优先级高于cdn与nonce的自动回退逻辑。返回的 handler 是一个同步函数直接构造new Response(html, { status: 200, headers: { Content-Type: text/html } })。这正是 0.9.0 引入的同步路由处理器行为与 Next.js App Router 的GET约定完全兼容。CSPnonce在严格安全策略下运行 API Reference0.11.00.11.0 是 CHANGELOG 中信息量最大的功能版本它引入了nonce选项用于支持 Content Security PolicyCSP。changelog 原文给出的用法如下ApiReference({ url: /openapi.json, // Match this value in your script-src CSP directive. nonce: r4nd0m, })当你传入nonce后渲染出的 HTML 会把这个值盖到内联script、CDNscript标签、Scalar 自己的style标签上同时输出一个配套的meta propertycsp-nonce。这样 API Reference 就能在严格的script-src不含unsafe-inline、不含unsafe-eval策略下正常运行。底层实现nonce 是如何打上去的渲染 HTML 的核心实现在 packages/client-side-rendering/src/html-rendering.ts。关键细节nonceAttribute(nonce)会生成带前导空格的nonce...属性并且通过escapeHtmlAttribute对 nonce 做 HTML 属性转义防止属性注入攻击对应测试用例 escapes the nonce to prevent attribute injection。meta propertycsp-nonce content...会被写入headstandalone bundle 在运行时读取该 meta 并把它应用到自身动态注入的样式表上bundle 以useStrictCSP模式构建时。nonce 为undefined时不输出任何nonce属性也不输出csp-noncemeta有对应单测覆盖。一个容易被忽略的机制nonce 会改变脚本加载策略html-rendering.ts中关于getScriptTags的注释揭示了 nonce 的一个连带影响默认情况下集成会加载现代、代码分割的 ESM 构建script typemodule但当设置了nonce时会自动回退到经典的单文件 UMD bundlescript srcScalar.createApiReference。原因是 ESM 构建通过原生import拉取分块而这些后续请求无法携带 nonce在严格的 nonce-basedscript-src策略下会被拦截UMD 是单文件不存在该问题。如果你希望强制使用 ESM 构建例如你的 CSP 采用了strict-dynamic可以显式传bundle: true或一个具体的 ESM 构建 URL。相关测试见 packages/client-side-rendering/src/html-rendering.test.ts覆盖了设置 nonce 时默认用 UMD 并应用 nonce、bundle 显式启用时仍用 ESM、输出 csp-nonce meta、不传 nonce 时不输出任何 nonce 属性等场景。局限性说明changelog 原话changelog 明确提醒style-src仍然需要unsafe-inline。因为 API Reference 会渲染内联的style…属性而 CSP nonce 只能作用于script、style和link元素永远无法授权内联 style 属性因此仅靠 nonce 的style-src是不可能的。这个能力的收益是让script-src可以做到完全严格。版本演进时间线从 0.1.0 到 0.11.18完整历史见 integrations/nextjs/CHANGELOG.md这里按里程碑梳理出最有价值的节点0.1.x诞生与形态定型0.1.0新增 Next.js 组件包装added Next.js component wrapper forscalar/api-reference。0.1.1适配器迁移为 API Route 形态放行 Next.js 14allow Next.js 14。0.1.46把 components 的 CSS 重新移回 JS 内部importing the css file is no longer needed——集成方从此不再需要手动引入 CSS。0.2.x解析引擎迁移0.2.0迁移到scalar/openapi-parser。0.2.5新增 OAuth2 implicit 登录流程支持移除全局 body margin reset。0.3.x主题体系重构0.3.0主题变量统一重命名——所有--theme-*变量改为--scalar-*rename all--theme-_variables to--scalar-_。如果你自定义过主题变量升级到该版本及以上时需要同步改名。0.3.23发布时添加 provenance 声明供应链可溯源。0.3.41intro cards 重新设计。0.4.x工程化与能力补全0.4.12新增url支持。0.4.47 / 0.4.48把react、next调整为 peer dependency并从构建中排除 React避免版本冲突。0.4.84新增 next.js OpenAPI 生成集成对应仓库中的 packages/nextjs-openapi。0.4.93在集成层固定 CDN 版本pin cdn version in integrations。0.4.96新增框架标识符即_integration: nextjs的由来。0.4.100启用noUncheckedIndexedAccess类型安全规则。0.4.101持续跟随scalar/types类型包升级。0.5.x / 0.6.xReact 19 与渲染层抽离0.5.0React 19 升级minor bump0.4.47 之后 React 为 peer dependency因此升级 React 19 不再引发版本冲突。0.6.0HTML 渲染逻辑收归scalar/coreuse html rendering lib fromscalar/core。0.7.0破坏性变更——配置扁平化remove the spec prefix, makecontentandurltop-level attributes。这是 0.7.0 之前用户升级时需要重点关注的迁移点已在上一节详述。0.8.0 / 0.9.xNode 版本与路由行为0.8.0要求 Node 20 及以上。0.9.0ApiReference改为返回同步路由处理器。0.9.2放宽nextpeerDependency 范围以支持 Next.js v16。0.9.15从 star exports 改为 named exportsuse named instead of star exports对应 integrations/nextjs/src/index.ts 中export { ApiReference } from ./ApiReference的写法。0.10.xNode 22 与渲染层再迁移0.10.0Node 要求提升到22 (LTS)同步体现在 package.json 的engines字段。0.10.9集成层迁移到 client-side rendering 包migrate integrations to client-side rendering package即现在源码中import { renderApiReference } from scalar/client-side-rendering的直接来源。0.10.16npm trusted publishing 重发布无功能变化。0.11.x安全能力与发布供应链0.11.0新增nonce选项CSP 支持详见前文。0.11.10修复 README 发布元数据——README 生成器在 package.json 中的元数据字段从readme改名为scalarReadme。原因写得很清楚npm 把readme字段本身当作 README 文本受影响的包因此曾在 registry 上发布成字面量[object Object]而不是真正的 README.md。现在 package.json 中的字段确认为scalarReadme见 integrations/nextjs/package.json。0.11.16 / 0.11.17通过 npm trusted publishing 重发布所有包无功能变更。源码与测试验证适配器契约单测覆盖的行为契约integrations/nextjs/test/ApiReference.test.ts 用 Vitest 固化了这个适配器的核心契约ApiReference({})返回一个函数handler调用 handler 返回Response实例status 200Content-Type: text/html底层renderApiReference被调用时config中会合并默认的_integration: nextjs用户配置如title优先handler 返回的 body 与renderApiReference产出的 HTML 完全一致。这些断言与 0.9.0同步路由处理器的设计互相印证。渲染管线的调用链一次请求的完整链路是Next.js 调用ApiReference({...})返回的 handlerhandler 拆分出cdn、pageTitle、nonce把其余配置作为config传入renderApiReferencerenderApiReference生成完整 HTML 字符串title、viewport、可选的csp-noncemeta、内联style带 custom theme、div idapp以及按bundle/cdn/nonce策略选定的script标签配置对象通过serializeConfigToJs序列化进内联脚本——它比JSON.stringify更强的地方在于能保留函数类型的属性如onBeforeRequest等请求钩子通过Function.prototype.toString()输出为字面量 JS 源码从而让回调在写入 inlinescript后依然可用见 packages/client-side-rendering/src/html-rendering.ts。注意序列化要求函数必须是箭头函数或function表达式对象方法简写onBeforeRequest(request) {}无法序列化成合法的独立表达式。依赖与兼容性矩阵以当前仓库为准integrations/nextjs/package.json维度要求来源Node.js22engines对应 0.10.0 起package.json / CHANGELOGnext^15.0.0 \|\| ^16.0.0peerDependencies0.9.2 起支持 v16package.json / CHANGELOGreact^19.0.0peerDependencies0.5.0 起package.json / CHANGELOG运行时依赖scalar/client-side-renderingworkspace 包0.10.9 起package.json / CHANGELOG包同时提供 ESMdist/index.js与 CJSdist/index.cjs双格式导出type: module类型声明为dist/index.d.ts。升级与迁移注意事项清单0.7.0 之前的项目把spec.url/spec.content改写为顶层url/content。使用自定义主题变量将--theme-*前缀改为--scalar-*0.3.0。Node 版本0.10.0 起需要 Node ≥ 220.8.0 阶段要求 Node ≥ 20。React / Next 版本0.5.0 起 React 为 peer dependency 且要求 19Next 的 peer 范围为^15 || ^16。导入方式使用 named importimport { ApiReference } from scalar/nextjs-api-reference0.9.15 起不再依赖 star exports。CSP 场景传nonce即可让script-src完全严格无需unsafe-inline/unsafe-eval但style-src仍需unsafe-inline如需在 strict CSP 下强制 ESM 构建显式传bundle: true。CSS 无需手动引入0.1.46 起组件 CSS 已内置于 JS。延伸阅读集成包完整说明与 Quickstartintegrations/nextjs/README.md版本历史全文integrations/nextjs/CHANGELOG.md适配器实现integrations/nextjs/src/ApiReference.ts、类型定义 integrations/nextjs/src/types.ts、默认主题 integrations/nextjs/src/custom-theme.ts测试契约integrations/nextjs/test/ApiReference.test.ts底层 HTML 渲染与 CSP 实现packages/client-side-rendering/src/html-rendering.ts 及其测试 html-rendering.test.ts完整配置项参考documentation/configuration.md可运行的示例工程examples/nextjs-api-reference配套的 OpenAPI 生成集成packages/nextjs-openapi【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
