在 SvelteKit 中集成 Scalar API Reference从安装、路由挂载到主题定制与 CSP 加固【免费下载链接】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本篇指南聚焦 Scalar 开源仓库中的 SvelteKit 官方集成包scalar/sveltekit讲解如何在 SvelteKit 项目中通过一个纯函数式的 Server Handler 将 OpenAPI/Swagger 文档渲染为交互式 API 文档页面。读完本文你将掌握安装与路由挂载、配置项url/content/sources、主题定制以及基于 nonce 的内容安全策略CSP加固方案。scalar/sveltekit的定位非常明确——它是一个SvelteKit 服务端处理器server handler负责把 OpenAPI/Swagger 文档渲染成美观、可交互的 API 文档页面。它不依赖任何前端组件挂载逻辑而是由服务端直接生成一段完整的 HTML 字符串并作为Response返回浏览器端再通过 CDN 加载 Scalar 的运行时完成渲染。快速上手安装与最小可运行示例安装命令与仓库内文档一致npm install scalar/sveltekit从 integrations/sveltekit/package.json 可以看到该包的使用前提Node.js 版本engines.node 22LTS来自 CHANGELOG 0.2.0 的版本提升说明peerDependenciessveltejs/kit ^2.57.1与svelte ^5.55.2即需要 SvelteKit 2.x Svelte 5 环境运行时依赖仅一个scalar/client-side-rendering负责把配置序列化并拼装出完整 HTML。在 SvelteKit 项目中把 API Reference 挂在任意server.ts路由上即可。以官方集成文档 documentation/integrations/sveltekit.md 中的示例为基础// routes/server.ts import { ScalarApiReference } from scalar/sveltekit import type { RequestHandler } from ./$types const render ScalarApiReference({ url: https://registry.scalar.com/scalar/apis/galaxy?formatjson, }) export const GET: RequestHandler () { return render() }要点在于ScalarApiReference(config)被调用一次返回一个同步的() Response函数这一设计在 CHANGELOG 0.1.27 中明确为 makeScalarApiReferencereturn a synchronous route handler然后在GET处理器里调用它并把返回值直接返回。默认情况下路由会渲染在/下你也可以把它放到routes/api-docs/server.ts这样的路径上。适配器原理一个返回 HTML 的 Server Handler整个包的源码只有三个文件麻雀虽小五脏俱全。入口 integrations/sveltekit/src/index.ts 只有一行export { ScalarApiReference } from ./scalar-api-reference.js核心实现位于 integrations/sveltekit/src/scalar-api-reference.ts全文仅 33 行完整逻辑如下import { renderApiReference } from scalar/client-side-rendering import { customTheme } from ./custom-theme.js import type { ApiReferenceConfiguration } from ./types.js /** * The default configuration for the API Reference. */ const DEFAULT_CONFIGURATION: PartialApiReferenceConfiguration { _integration: svelte, } export const ScalarApiReference (givenConfiguration: PartialApiReferenceConfiguration): (() Response) { // Merge the defaults 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 }, }) } }从中可以提炼出三个关键实现事实默认配置注入集成标识DEFAULT_CONFIGURATION设置了_integration: svelte让 Scalar 运行时知道当前页面由哪个框架集成渲染便于统计与行为微调你传入的配置会浅合并覆盖默认值CHANGELOG 0.1.15 记录了这一默认值的引入。参数分流cdn、pageTitle、nonce三个字段被单独解构出来作为 HTML 渲染层的选项处理其余配置全部原样下发给renderApiReference。响应构造渲染结果是一个完整 HTML 文档字符串包在status: 200、Content-Type: text/html的Response中返回——这正是它能在server.ts里作为请求处理器直接使用的原因。配置类型定义在 integrations/sveltekit/src/types.tsimport type { HtmlRenderingConfiguration } from scalar/client-side-rendering /** * The configuration for the Scalar API Reference for SvelteKit */ export type ApiReferenceConfiguration HtmlRenderingConfiguration也就是说scalar/sveltekit不定义自己的专属配置项而是完整复用scalar/client-side-rendering的HtmlRenderingConfiguration即 Scalar 的「通用配置」universal configuration。这意味着你在官方配置文档 documentation/configuration.md 中看到的绝大多数配置项都可以原样传给ScalarApiReference。配置 API 文档来源url、content 与 sources根据 documentation/configuration.md要让页面渲染出内容只需提供一份 API 文档共有三种方式方式一URL推荐ScalarApiReference({ url: /openapi.json, })支持绝对地址或相对地址内容可以是 JSON 或 YAML这是官方推荐的方式浏览器可以缓存文档即使文档规模不断增长后续访问也很快相对路径url: /openapi.json与前面示例中的远程地址Scalar Registry 提供的 galaxy 示例 API在 SvelteKit 中同样适用。方式二content内联内容ScalarApiReference({ content: { openapi: 3.1.0, info: { title: Hello World, version: 1.0.0 }, paths: { // … } }, })直接传入 JSON/YAML 字符串适合快速验证。注意官方文档提示对于大型文档这种方式可能影响性能追求最优性能时优先使用 URL。另外在底层 packages/client-side-rendering/src/html-rendering.ts 的getConfiguration中还有一个细节content可以是函数渲染时会先执行函数取值并且当content与url同时存在时content会被删除url优先。方式三sources多文档ScalarApiReference({ sources: [ { title: Scalar Galaxy, // 可选缺省时回退为 API #1 slug: scalar-galaxy, // 可选会自动根据 title 或索引生成 url: https://registry.scalar.com/scalar/apis/galaxy?formatjson, }, { url: https://example.com/openapi.json, }, { content: { openapi: 3.1.1, … }, }, ], })列表中的第一份文档是默认文档如果希望显式指定默认文档可以给某一项加default: true。每项都支持url或content的组合title与slug用于在 UI 和 URL 中区分不同文档。页面级选项pageTitle、cdn 与加载方式ScalarApiReference接受的配置在传给renderApiReference时pageTitle、cdn和nonce会被单独提取。结合 packages/client-side-rendering/src/html-rendering.ts 的实现pageTitle默认值为Scalar API Reference会写入生成 HTML 的title标签renderApiReference第 130 行且会做 HTML 转义防止注入cdn指定加载 Scalar 运行时的 CDN 地址。包内定义了两个默认值DEFAULT_CDNhttps://cdn.jsdelivr.net/npm/scalar/api-reference经典 UMD 全量包与DEFAULT_ESM_CDNhttps://cdn.jsdelivr.net/npm/scalar/api-reference/esm.js按需拆包的 ESM 构建是默认选择。一旦显式传入cdn会回退到 UMD 加载方式bundletrue/false/ URL 字符串优先级高于cdn与nonce用于强制选择 ESM 或 UMD 构建。底层脚本注入逻辑在getScriptTags中默认情况下生成script typemodule通过import { createApiReference } from esm导入并调用createApiReference(#app, {…配置…})UMD 模式下则先加载script src再调用全局Scalar.createApiReference(#app, …)。主题与自定义样式从默认主题到 customCssscalar/sveltekit自带一套 SvelteKit 专属主题定义在 integrations/sveltekit/src/custom-theme.ts 中。它是一段完整的 CSS 字符串通过 Scalar 的 CSS 变量体系同时覆盖明暗两套配色暗色模式.dark-mode主背景#000000强调色--scalar-color-accent: #3070ec文字颜色分级rgba(255,255,255,0.9 / 0.62 / 0.44)亮色模式.light-mode背景#fff强调色同为#3070ec还包含对文档头部.t-doc__header带backdrop-filter: saturate(180%) blur(5px)毛玻璃效果、侧边栏.t-doc__sidebar、卡片.scalar-card以及按钮、状态色、滚动条等细节的定制。这套主题如何生效在html-rendering.ts的getStyles函数中可以看到完整的样式组装逻辑如果配置里给了customCss会先输出这段自定义 CSS如果没有显式设置theme则会注入custom-theme.ts提供的默认主题两者都没有时不输出style标签。因此在 SvelteKit 中做样式定制有两个入口一是通过配置项customCss追加自己的 CSS可以覆盖上述 CSS 变量二是设置theme选择 Scalar 内置主题。主题相关能力的更全面说明见 documentation/themes.md。CSP 加固nonce 选项的正确用法对于将 API 文档站点部署在严格 CSP 策略下的团队scalar/sveltekit从 0.3.0 起提供了nonce选项见 integrations/sveltekit/CHANGELOG.md 0.3.0 条目ScalarApiReference({ url: /openapi.json, // 与你在 script-src 指令中配置的 nonce 保持一致 nonce: r4nd0m, })其底层机制在html-rendering.ts中有详细注释可以归纳为nonce 会被盖章到所有内联标签上包括内联的script、CDN 的script标签、Scalar 自己的style标签以及一个meta propertycsp-nonce标签后者让运行时在动态注入样式表时也能复用同一 nonce支持严格的 script-src启用 nonce 后script-src指令可以完全去掉unsafe-inline和unsafe-evalstyle-src 仍需unsafe-inline因为 API Reference 会渲染大量内联style…属性而 CSP nonce 只能作用于script、style、link元素无法授权内联属性因此style-src无法做成 nonce-onlynonce 与加载方式的联动设置 nonce 时默认走单文件 UMD 包因为 ESM 构建通过原生import拉取分块这些请求无法携带 nonce在无strict-dynamic的严格策略下会被拦截若 CSP 使用了strict-dynamic可显式传bundle: true强制 ESM。另外nonce在写入 HTML 时经过了双重转义escapeHtmlAttribute同时转义 HTML 特殊字符与双引号避免 nonce 值逃逸出属性边界——这是一个值得注意的安全细节。版本、维护与后续查阅当前仓库中该包版本为0.3.18见 integrations/sveltekit/package.json构建流程为svelte-package --input src发布前会执行pnpm build publint校验每次发布均伴随上游scalar/core的依赖更新说明该集成持续跟随 Scalar 核心能力演进完整变更历史可查阅 integrations/sveltekit/CHANGELOG.md其中值得关注的节点包括0.1.0 首次引入 SvelteKit 集成、0.1.27 改为同步路由处理器、0.2.0 要求 Node 22、0.3.0 新增 CSP nonce 支持该集成所在包根目录的 integrations/sveltekit/README.md 为自动生成文件由 Scalar README 生成器维护概述了包的定位与许可证MIT信息。总结scalar/sveltekit是一个极简而完整的 SvelteKit 官方集成它把「从 OpenAPI/Swagger 文档到交互式 API 文档页面」的复杂链路收敛为一个同步的 Server Handler。开发者只需要在任意server.ts中创建渲染函数并返回即可获得带暗色主题、多文档切换、可配置 CDN 加载方式甚至支持严格 CSP 的 API 文档页面。配合通用配置项url、content、sources与customCss/theme定制能力它能够无缝嵌入各类 SvelteKit 站点作为对外 API 文档的官方入口。【免费下载链接】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），仅供参考