深入 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/scalarscalar/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 titleScalar API Reference/title meta charsetutf-8 / meta nameviewport contentwidthdevice-width, initial-scale1 / /head body div idapp/div !-- 加载脚本 -- script srchttps://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?formatjson, // 避免 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.createApiReferencev1.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}modelsSectionLabelModels / 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/。nonceContent Security Policy 支持v1.59.0 为 CSP 场景新增nonce选项ApiReference({ url: /openapi.json, // 在 script-src 指令中匹配该值 nonce: r4nd0m, })传入nonce后渲染出的 HTML 会把它盖印到内联script、CDNscript标签、Scalar 自身的style标签以及一个匹配的meta propertycsp-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 无根级securityhttp、oauth2、openIdConnect、apiKey等与 OpenAPI 共享的方案获得完整输入 UIAsyncAPI OAuth2 的availableScopes映射到 OpenAPIscopesbroker 专属类型如userPassword、scramSha256仍会出现在选择器中但暂无专用输入并显示 “not supported yet” 消息而非误导性的 “missing a type”。组合 Schema 渲染allOf / oneOf / anyOf 的正确性CHANGELOG 中大量 Patch 围绕组合 Schemacomposition的渲染正确性这反映了引擎在“扁平化展示”与“保持语义”之间的精细平衡v1.64.0allOf下多个并排oneOf/anyOf分组各自渲染独立选择器请求示例按分组保持同步保留allOf旁的兄弟propertiesrequired取并集父 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 树将PaginatedResponseT这类泛型模式绑定到具体的$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链接统一补充relnoopener noreferrer。配套地scalar/helpers新增了isSafeUrl与sanitizeUrlpackages/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。辅助函数isPlainLeftClickscalar/helpers的dom/is-plain-left-click用于判断一次点击是否应被劫持做客户端导航。深度链接的另一面是锚点滚动v1.60.0 修复了指向折叠区内 Schema 属性的锚点——现在深层链接会展开目标路径上的 disclosure 并滚动到位无需开启expandAllSchemaPropertiesv1.62.5 为响应属性锚点添加responses标记使首次加载能定位并展开目标操作且expandAllResponses关闭时也可通过深层链接展开并滚动。性能懒加载、代码分割与 ESM 构建性能是 CHANGELOG 反复出现的主题分为渲染层与构建层两条线渲染层v1.49.0 引入懒渲染lazy renderingv1.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-*.jsAgent Scalar 聊天界面已用defineAsyncComponent包裹变成按需加载的chunks/AgentScalarChatInterface-*.js约 200 KBscalar/icons/library的 84 个按图标动态导入合并为单个chunks/icons-*.js。初始同步加载从约 3.32 MBUMD降至约 2.73 MBESM。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.0API 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-2xl12px、--scalar-radius-3xl16px与--scalar-radius-fullpill/圆形配套rounded-2xl、rounded-3xlTailwind 工具类开始输出 CSS。无障碍v1.64.1 修复 axe-core 报出的 ARIA 违规——侧边栏选中项改用aria-currentpage链接/按钮上使用aria-selected不合法搜索触发改为普通具名按钮aside不再设置非法的rolenavigationv1.64.0 修复CompactSection折叠触发器无名称与aria-controls指向自身的问题改用aria-labelledby指向可见标题避免 WCAG 2.5.3 Label in Name 风险。v1.55.0 起操作路径旁显示 “Auth Required / Auth Optional” 徽章悬停展示方案名、类型与所需 scopev1.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 重定向重构为路由无关、列表驱动的引擎——重定向基于裸导航 idhash、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 mismatchv1.57.1 将文档级监听器绑定到AbortControllerdestroy()时统一移除修复 AstrorenderModeclient视图切换下的监听器泄漏。URL 处理v1.57.1 引入请求构建的Resultok/err与稳定错误码MISSING_REQUEST_SERVER_BASE、INVALID_REQUEST_FACTORY_URL、BUILD_REQUEST_FAILED无效 URL 在发送前被拦截。版本、依赖与运行时要求Node.jsv1.47.0 起要求 Node.js 22LTS。Vuev1.64.1 升级到 Vue 3.5.40v1.39.0 升级到 Vue 3.5.21。zodv1.37.0 迁移到 Zod 4v1.67.0 收敛 catalog 到^4.4.3以消除双副本。Storybookv1.67.0 升级到 Storybook 10.5.10并移除第三方暗色模式 addonv1.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 truthsidebar 在 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 既是功能清单也是排查行为差异、理解配置生效边界的第一手资料。【免费下载链接】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），仅供参考