深入 @scalar/api-reference：从 CHANGELOG 看 Scalar 文档引擎的功能演进与配置详解-创锋一号

深入 @scalar/api-reference：从 CHANGELOG 看 Scalar 文档引擎的功能演进与配置详解

【免费下载链接】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/api-reference是开源 API 平台 Scalar 的核心渲染包，负责把 OpenAPI / Swagger / AsyncAPI 文档渲染为可交互、可搜索、可发请求的 API 参考文档。本文以该包 CHANGELOG.md 的演进记录为主线，系统梳理其公开配置项、OpenAPI 扩展、安全模型、SEO 能力与性能优化手段，并结合 ApiReference.vue 等源码确认关键配置的实际落地方式。读完本文，你将掌握如何通过配置项定制文档行为、如何利用x-scalar-*扩展增强文档语义，以及该引擎在组合 Schema、AsyncAPI、CSP 安全与路由可抓取性上的底层设计。

包定位与基本使用

@scalar/api-reference位于 packages/api-reference，是整个 Scalar 生态中负责“文档渲染”的包。它的输入是 OpenAPI/Swagger 文档（也可以是 AsyncAPI 文档），输出是一整套交互式界面：左侧导航侧边栏、操作（Operation）列表、Models/Schemas 区、响应示例、代码片段、认证选择器，以及内嵌的“测试请求”能力（由 @scalar/api-client 提供）。

包的 README.md 给出了最轻量的 CDN 集成方式：

<!doctype html> <html> <head> <title>Scalar API Reference</title> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> </head> <body> <div id="app"></div> <!-- 加载脚本 --> <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script> <!-- 初始化 Scalar API Reference --> <script> Scalar.createApiReference('#app', { // OpenAPI/Swagger 文档地址 url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=json', // 避免 CORS 问题 proxyUrl: 'https://proxy.scalar.com', }) </script> </body> </html>

包内还提供cdn.html与esm.js两个入口文件：esm.js对应https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js这个短 CDN 地址（v1.66.0 起提供）。除了 UMD 全局脚本（window.Scalar.createApiReference），v1.58.0 还新增了dist/browser/standalone.esm.jsESM 独立构建，既可作副作用脚本运行，也导出createApiReference供 ESM 消费者直接使用。

配置项详解：从请求体视图到页面标题

CHANGELOG 记录了多个对使用者直接可见的配置项，下面按功能逐一说明其作用与源码佐证。

defaultRequestBodyView：默认请求体视图

v1.68.0 新增配置项defaultRequestBodyView，用于让请求体编辑器默认以“表单视图”（Form view）打开：

Scalar.createApiReference('#app', { url: '/openapi.json', defaultRequestBodyView: 'form', // 可选 'raw'（默认）与 'form' })

该配置默认值为raw，且当请求体无法以表单形式展示时会自动回退到raw。它也支持通过 OpenAPI 扩展x-scalar-default-request-body-view在文档中声明，并且该扩展支持按来源（per source）生效。在 ApiReference.vue 中可以看到config.defaultRequestBodyView被读取并传递的代码路径。

pluginUrls：从 URL 加载插件

v1.64.0 新增pluginUrls配置选项，用于从 URL 加载 API Reference 插件：

每个条目必须指向一个以default导出插件对象的 ESM 模块（与plugins条目形状一致）；
standalone 构建（Scalar.createApiReference）会在 API Reference 挂载前导入这些模块，并把默认导出注册到直接传入的plugins旁边；
与plugins不同，pluginUrls是 JSON 可序列化的，因此以 JSON 形式传递配置的集成方式（例如 Docker 容器、Scalar for Aspire）可以在不替换整个 bundle 的情况下加载插件。

expandAllSchemaProperties：默认展开嵌套属性

v1.59.0 引入expandAllSchemaProperties配置项：启用后，嵌套的 Schema 属性默认全部展开，同时保留“Show/Hide Child Attributes”按钮供手动折叠。展开是循环安全的：每个有限分支都会被完整展开，而自引用（$ref或内联）Schema 会在即将无限递归处停止。

setPageTitle：定制浏览器标签页标题

v1.58.0 新增setPageTitle函数配置，用于控制浏览器标签页标题。每当视口内的章节变化（点击侧边栏、滚动、切换文档）时它都会被调用，并接收当前章节标题与活动文档：

setPageTitle: ({ title, document }) => `${document.title} – ${title}`

modelsSectionLabel：Models / Schemas 术语切换

v1.58.0 新增modelsSectionLabel配置（'Models' | 'Schemas' | string），用于在侧边栏、内容区和搜索中使用 OpenAPI 风格的 “Schemas” 术语。在 ApiReference.vue 中，该值通过mergedConfig.value.modelsSectionLabel ?? DEFAULT_MODELS_SECTION_LABEL参与合并，并驱动侧边栏条目、内容标题与搜索索引的生成；v1.59.3 还支持把旧的models/<name>书签重定向到自定义的 section slug（如schemas/）。

nonce：Content Security Policy 支持

v1.59.0 为 CSP 场景新增nonce选项：

ApiReference({ url: '/openapi.json', // 在 script-src 指令中匹配该值 nonce: 'r4nd0m', })

传入nonce后，渲染出的 HTML 会把它盖印到内联<script>、CDN<script>标签、Scalar 自身的<style>标签，以及一个匹配的<meta property="csp-nonce">上，从而允许 API Reference 在严格的script-src下运行，无需unsafe-inline与unsafe-eval。需要注意：style-src仍需要'unsafe-inline'，因为文档渲染了内联style="…"属性，而 CSP nonce 无法授权这类属性（nonce 只作用于<script>、<style>与<link>元素）。

customFetch：自定义请求函数

v1.57.3 新增customFetch配置项，并将其转发给 API Client，使所有请求（包括 “Test Request” 调用）都走自定义 fetch，从而支持credentials: 'include'等场景。之前的fetch选项被标记为废弃，并会在迁移时自动映射（同时输出控制台警告）。

服务器选择与会话保持

v1.64.1 修复了一个关键交互问题：推送配置更新（例如通过updateConfiguration刷新认证 token）时，store 会 rebase 文档，此前会把服务器选择器重置回第一个服务器；现在用户选中的服务器会在配置更新后保留。

OpenAPI 扩展（x-scalar-*）与第三方扩展

CHANGELOG 记录了大量自定义扩展的读取逻辑，这些扩展让文档作者可以在不写前端代码的前提下增强参考文档。

x-scalar-links：简介区附加链接

v1.62.0 新增x-scalar-linksOpenAPI 扩展，可在简介区（Introduction）的联系方式、许可证、服务条款链接旁渲染额外的具名链接（如隐私政策、法律声明页）。v1.64.1 的安全加固中对这些链接目标做了协议白名单校验。

x-scalar-sdk-installation：自定义 SDK 安装说明

v1.59.0 支持从x-scalar-sdk-installation读取自定义 SDK 安装说明并展示在简介卡片中（无该扩展时回退到客户端选择器）。每个条目包含lang与 Markdown 格式的description，单个标签页即可渲染带语法高亮代码块的丰富说明（例如 Java 的 Maven 与 Gradle）。v1.59.2 恢复了废弃的source安装命令支持：设置后它会作为围栏代码块追加到description后（或在没有description时单独使用）。v1.63.0 进一步导出SdkInstallationInstructions与getRenderableSdks（来自@scalar/api-reference/blocks），让自定义布局的消费方可以重新渲染该能力。

代码示例扩展读取与优先级

v1.59.0 起，除了x-codeSamples，代码示例选择器还会读取x-scalar-examples、x-stainless-snippets、x-stainless-examples与x-readme.code-samples。当一个操作上存在多个来源时，按优先级取最高者：

x-scalar-examples > x-stainless-snippets > x-stainless-examples > x-readme > x-codeSamples

其他 OpenAPI 3.2 与 Schema 相关扩展

v1.66.0 支持 OpenAPI 3.2 嵌套 tags：导航树通过tag.parent字段构建任意深度层级；无自身操作的父 tag 被当作 section，既有操作又有子节点的 tag 则两者兼是；原生parent嵌套优先于x-tagGroups（后者作为旧文档的回退方案）。Tag Object 新增的parent、kind、summary字段在 @scalar/workspace-store 与 @scalar/schemas 中均有识别，summary在x-displayName之后作为 tag 标题。v1.62.1 还支持 NSwag 风格的discriminator.mapping（无显式 oneOf/anyOf 的多态类型）。

AsyncAPI 支持：从通道到认证选择器

CHANGELOG 清晰地展示了 AsyncAPI 支持的分阶段落地，这是 v1.4x–1.6x 期间最显著的 Minor 能力：

v1.58.0：将components.schemas作为 Models 渲染（与 OpenAPI Schema 一致，出现在侧边栏与内容区）；通道（Channel）以通道地址为标题、通道描述为正文在内容区渲染；从info.description提取标题进侧边栏与搜索。
v1.59.0：渲染通道地址参数（{param}占位符，复用 OpenAPI 操作的参数列表组件，展示enum、default、examples）；新增 AsyncAPI 服务器选择器（按host/protocol/pathname命名映射，展示拼接后的连接 URL），并通过asyncapi-server:update:selected与asyncapi-server:update:variables事件持久化选择。
v1.61.0：在通道内嵌套渲染 AsyncAPI 操作及其消息（payload 与 header Schema），现代与经典布局均支持；通道头部列出可用服务器与协议，每条消息表面其承载的协议。
v1.62.0：侧边栏新增 AsyncAPI 协议与服务器选择器（类似多文档选择器），可按协议/服务器过滤导航。
v1.62.6：为 AsyncAPI 文档渲染文档级认证：简介区展示与 OpenAPI 相同的 Authentication 选择器，从components.securitySchemes填充，需求由所有服务器的security并集推导（AsyncAPI 无根级security）；http、oauth2、openIdConnect、apiKey等与 OpenAPI 共享的方案获得完整输入 UI，AsyncAPI OAuth2 的availableScopes映射到 OpenAPIscopes；broker 专属类型（如userPassword、scramSha256）仍会出现在选择器中但暂无专用输入，并显示 “not supported yet” 消息而非误导性的 “missing a type”。

组合 Schema 渲染：allOf / oneOf / anyOf 的正确性

CHANGELOG 中大量 Patch 围绕组合 Schema（composition）的渲染正确性，这反映了引擎在“扁平化展示”与“保持语义”之间的精细平衡：

v1.64.0：allOf下多个并排oneOf/anyOf分组各自渲染独立选择器，请求示例按分组保持同步；保留allOf旁的兄弟properties，required取并集，父 Schema 自身的注解优先于被继承的基础 Schema。
v1.62.4 / v1.61.0：修复allOf提取共享属性时oneOf/anyOf分支覆盖基础字段的问题；对象自身的properties与组合关键字（anyOf/oneOf/allOf/not）并列时正常渲染。
v1.67.0：修复 oneOf 选择器标签显示共享 allOf 基名而非分支自身名的问题（单一$ref的 allOf 继承模式）。
v1.66.0：组合 Schema 无自身属性时显示自身description（此前会错误地显示第一个 allOf 成员的描述）。
v1.62.1：支持 JSON Schema 2020-12 的$dynamicRef——引擎把动态作用域贯穿 Schema 树，将PaginatedResponse<T>这类泛型模式绑定到具体的$dynamicAnchor，渲染出User[]而非空形状；同时修复了经 allOf 分支自引用导致的Maximum call stack size exceeded崩溃（v1.58.0 也修复了mergeAllOfSchemas中的自引用循环）。

枚举渲染方面，v1.64.0 修复了数组items内枚举的x-enum-varnames、x-enumNames、x-enumDescriptions元数据被从外层 Schema 读取而丢失的问题——现在值与元数据从同一 Schema 读取；v1.32.4 起支持渲染x-enum-varnames。

安全加固：对抗不可信文档

v1.64.1 对“不可信 OpenAPI 文档”做了系统性加固，这在文档渲染类产品中非常关键：

文档来源的链接目标（info.license.url、info.termsOfService、info.contact.url、externalDocs.url、x-scalar-links）与直接下载链接现在都会经过协议白名单校验，文档无法再渲染出点击即执行脚本的javascript:链接，不安全值回退为纯文本；
deepMerge（供导出的createEmptySpecification使用）不再写入原型链，文档无法通过__proto__、constructor、prototype给Object.prototype添加属性；同名键会保留为普通数据，Schema 仍可描述名为constructor的属性；
customCss无法再闭合注入的<style>标签（这在服务端渲染时尤其重要，因为该值会原样进入 HTML 流）；
剩余的target="_blank"链接统一补充rel="noopener noreferrer"。

配套地，@scalar/helpers新增了isSafeUrl与sanitizeUrl（packages/helpers 的url/is-safe-url模块）。v1.59.0 的nonce配置是同一安全主题的另一半——严格script-src下的 CSP 运行。

SEO 与路由：让深度链接可被爬取、可被索引

v1.66.0 集中改进了侧边栏导航的可发现性，这是文档类应用 SEO 的核心：

服务端渲染暴露全部 URL：交互式侧边栏会把折叠分组的子项移出 DOM，导致未开启defaultOpenAllTags时，折叠 tag 内的操作与模型链接缺失于 SSR 输出。现在服务端渲染的 HTML 会额外包含一个隐藏的、扁平的纯锚点列表，覆盖所有导航条目，爬虫无需执行 JavaScript 即可发现全部深层链接；该列表在 hydration 后立即移除，不影响交互体验。
侧边栏从按钮改为锚点链接：@scalar/sidebar的ScalarSidebar与SidebarItem接受新的getHref回调，返回 URL 时条目渲染为真实链接；普通左键点击仍会触发selectItem做站内导航（阻止默认跳转），修饰键点击交给浏览器（可新标签打开）。@scalar/api-reference使用 SSR 安全的makeHrefFromId辅助函数生成与 history 推送 URL 一致的真实锚点。值得注意：使用路径路由（pathRouting）时链接可被搜索引擎抓取索引；哈希路由与 hash-base-path 路由下片段 href 改善了链接语义与新标签打开行为，但搜索引擎不把 fragment 当作独立 URL——若目标是 URL 发现，请配置pathRouting。
辅助函数isPlainLeftClick（@scalar/helpers的dom/is-plain-left-click）用于判断一次点击是否应被劫持做客户端导航。

深度链接的另一面是锚点滚动：v1.60.0 修复了指向折叠区内 Schema 属性的锚点——现在深层链接会展开目标路径上的 disclosure 并滚动到位，无需开启expandAllSchemaProperties；v1.62.5 为响应属性锚点添加responses标记，使首次加载能定位并展开目标操作，且expandAllResponses关闭时也可通过深层链接展开并滚动。

性能：懒加载、代码分割与 ESM 构建

性能是 CHANGELOG 反复出现的主题，分为渲染层与构建层两条线：

渲染层：v1.49.0 引入懒渲染（lazy rendering），v1.33.0 起迭代出“lazy loading v1.5”，v1.44.4 修复了懒加载队列的回归（防止已就绪条目被反复入队导致大 spec 滚动卡顿）。v1.64.0 支持在浏览器空闲时预加载多文档配置中的其他文档，使文档切换即时完成。v1.34.0 支持partial bundle to a depth的按需解析。

构建层：v1.58.0 的 ESM standalone 构建通过 Rolldown 原生 minifier 压缩并启用代码分割：

API Client 弹窗（请求编辑器、响应查看器、CodeMirror）改为onMounted内await import，约 265 KB 移入后台加载的chunks/modal-*.js；
Agent Scalar 聊天界面（已用defineAsyncComponent包裹）变成按需加载的chunks/AgentScalarChatInterface-*.js（约 200 KB）；
@scalar/icons/library的 84 个按图标动态导入合并为单个chunks/icons-*.js。

初始同步加载从约 3.32 MB（UMD）降至约 2.73 MB（ESM）。v1.67.0 还通过升级 zod catalog 到^4.4.3，使 standalone bundle 只携带单一 zod 副本，standalone.js减小约 68 KB 原始体积 / 18 KB gzip。v1.66.0 为 standalone 浏览器构建（dist/browser）附带 source map，方便调试配置错误。

本地化、主题与无障碍

本地化（v1.62.0）：API Reference UI 内置英语、俄语、西班牙语、法语、德语、简体中文与阿拉伯语翻译，阿拉伯语 locale 自动启用 RTL 方向；@scalar/helpers新增mergeObjects深合并辅助函数，用于把翻译覆盖合并到内置 locale 之上。

主题（v1.62.8）：圆角尺度改为从--scalar-radius派生——此前--scalar-radius-lg、--scalar-radius-xl、rounded-full相互独立，设置--scalar-radius: 0仍会残留圆角；现在覆盖单个变量即可重缩放界面所有圆角，0完全切方。新增--scalar-radius-2xl（12px）、--scalar-radius-3xl（16px）与--scalar-radius-full（pill/圆形），配套rounded-2xl、rounded-3xlTailwind 工具类开始输出 CSS。

无障碍：v1.64.1 修复 axe-core 报出的 ARIA 违规——侧边栏选中项改用aria-current="page"（链接/按钮上使用aria-selected不合法），搜索触发改为普通具名按钮，<aside>不再设置非法的role="navigation"；v1.64.0 修复CompactSection折叠触发器无名称与aria-controls指向自身的问题，改用aria-labelledby指向可见标题（避免 WCAG 2.5.3 Label in Name 风险）。v1.55.0 起操作路径旁显示 “Auth Required / Auth Optional” 徽章，悬停展示方案名、类型与所需 scope；v1.64.0 将所需 OAuth scopes 提升为描述下方的独立 “OAuth scopes” 小节（现代与经典布局、AsyncAPI 操作均适用）。

插件 API 与可组合性

插件系统在 v1.6x 快速扩展：

v1.60.0：新增content.start视图插槽，可在简介/Info 区之前（内容区顶部）渲染自定义组件；ViewComponent增加sidebar选项，插件可通过sidebar: { show: true, label: 'My Page' }在侧边栏显示自定义视图入口，点击滚动到位并随滚动高亮。
v1.62.5：插件生命周期钩子（onInit、onConfigChange）除config外新增只读的auth访问器，插件管理器暴露getAuthState()；插件可读取auth.export()、auth.getAuthSecrets(documentName, schemeName)、auth.getAuthSelectedSchemas(payload)而无法改动认证状态。
v1.62.6：修复插件auth访问器读取错误 store 的问题——现在从客户端 store 读取（API Reference 的 Authentication 面板正是把凭据写入该 store），插件能看到用户实际输入的密钥与选中的安全方案。
v1.61.0：新增requestBuilt客户端插件钩子与onRequestBuilt配置回调，收到即将发出 wire 的确切 fetchRequest（请求构建后、发送前触发，header 修改生效、body 字节与服务器收到的一致），可用于请求签名等场景。
v1.65.0：从@scalar/api-reference/components导出 AsyncAPI 内容组件（AsyncApiChannel、AsyncApiOperation、AsyncApiMessage、AsyncApiTraversedEntry），下游渲染器可在独立页面上渲染单个 channel/operation/message。
v1.39.0：新增content.end视图插槽（内容区末尾）。

值得关注的修复亮点与工程质量

除上述主题外，CHANGELOG 中还有一批体现工程质量的修复：

响应示例一致性：v1.67.0 修复响应示例面板未反映响应下拉所选 content-type 的问题；v1.64.0 让请求/响应示例选择器跨操作同步（选择 “Use case 1” 会在所有定义该示例的操作上同步选择同 key 示例，类似语言选择器的同步行为）。
模型名链接：v1.65.0 修复三类死链——hideModels或x-internal/x-scalar-ignore隐藏整个 Models 区时模型名改为纯文本；$ref不指向#/components/schemas/（指向 parameters、responses 或外部文件）时同样显示纯文本；x-tags分组下的模型链接通过从整个导航树收集模型条目而生效。
打印样式：v1.64.0 新增 print styles，打印/存 PDF 不再把展开内容叠加到后续文本上——固定视口应用布局被压平为普通文档流，隐藏导航与浮动 chrome，丢弃 sticky 定位与视口高度上限，长示例不再被截断，属性与卡片避免跨页断行。
路由重定向引擎：v1.59.3 把 URL 重定向重构为路由无关、列表驱动的引擎——重定向基于裸导航 id，hash、hash-base-path 与 path 路由自动生效。
路径项$ref解析：v1.59.3 修复 OpenAPI path items 使用components.pathItems引用时的解析——导航、mutator、搜索、markdown 导出都会在读取 HTTP 方法与路径级参数前解析 path-item 引用。
SSR 稳定性：v1.61.0 修复注入<style>标签的 HTML 转义导致的 hydration mismatch；v1.57.1 将文档级监听器绑定到AbortController，destroy()时统一移除（修复 AstrorenderMode="client"视图切换下的监听器泄漏）。
URL 处理：v1.57.1 引入请求构建的Result（ok/err）与稳定错误码（MISSING_REQUEST_SERVER_BASE、INVALID_REQUEST_FACTORY_URL、BUILD_REQUEST_FAILED），无效 URL 在发送前被拦截。

版本、依赖与运行时要求

Node.js：v1.47.0 起要求 Node.js >= 22（LTS）。
Vue：v1.64.1 升级到 Vue 3.5.40；v1.39.0 升级到 Vue 3.5.21。
zod：v1.37.0 迁移到 Zod 4，v1.67.0 收敛 catalog 到^4.4.3以消除双副本。
Storybook：v1.67.0 升级到 Storybook 10.5.10，并移除第三方暗色模式 addon；v1.41.0 已升级到 Storybook 10。
依赖关系：CHANGELOG 的 “Updated Dependencies” 部分显示该包深度依赖@scalar/workspace-store、@scalar/api-client、@scalar/components、@scalar/sidebar、@scalar/openapi-parser、@scalar/snippetz、@scalar/themes等兄弟包——其中 workspace-store 在 v1.39.0 起成为主要数据源（single source of truth），sidebar 在 v1.39.0 起迁移到共享侧边栏组件。

小结

透过 packages/api-reference/CHANGELOG.md 这 10941 行的演进记录，可以看到@scalar/api-reference的能力版图：以defaultRequestBodyView、expandAllSchemaProperties、setPageTitle、modelsSectionLabel、nonce、customFetch、pluginUrls等配置项构成的可定制面；以x-scalar-*扩展与多来源代码示例构成的文档语义增强层；以组合 Schema、$dynamicRef、枚举元数据为代表的渲染正确性投入；以 AsyncAPI 通道/消息/认证选择器为代表的双协议支持；以及贯穿始终的安全加固、SEO 路由、懒加载与代码分割。若你正在评估或集成 Scalar 的 API 文档能力，这份 CHANGELOG 既是功能清单，也是排查行为差异、理解配置生效边界的第一手资料。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析