scalar/api-client 视觉测试指南Web、App、Modal 三种布局的 Playground 启动与验收规范【免费下载链接】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-client是 Scalar 开源 API 平台中的 API 测试客户端提供请求编辑器、响应查看器、认证表单、环境管理与集合组织等完整能力。本文以该包维护文档 packages/api-client/AGENTS.md 为核心系统讲解如何在本地启动三种布局web / app / modal的 playground 进行视觉与功能测试覆盖每个布局的差异、逐项检查清单以及不同变更类型的测试时机并结合仓库源码说明底层原理。读完本文你将能像项目维护者一样快速启动客户端开发环境、按布局精准定位回归点并理解 modal 布局与 API Reference 的联动机制。包概述scalar/api-client的定位与三种布局从 packages/api-client/AGENTS.md 的 Package Overview 可知scalar/api-client是 Scalar 的 API 测试客户端核心能力包括请求编辑器request editorsURL 地址栏、方法选择、Body / Headers / Query / Path 参数编辑响应查看器response viewers状态码、响应头、带语法高亮的响应体认证表单authentication formsBearer、Basic、API Key、OAuth 等多种认证类型环境管理environment management变量管理与环境切换集合组织collection organization请求集合的树形组织与拖拽排序。该包以三种布局形态交付对应三种不同的挂载与交互场景布局说明web独立浏览器客户端聚焦单请求编辑与发送是默认开发目标app桌面应用风格的完整布局含侧边栏、集合、环境与工作区管理modal以覆盖层overlay形式弹出可嵌入 API Reference 中这一描述与源码目录结构相互印证packages/api-client/src/v2下按功能域拆分为blocksoperation-block、request-block、response-block、scalar-address-bar-block、scalar-auth-selector-block 等、featurescommand-palette、environments、modal、operation、search、components、helpers与hooks并在 packages/api-client/package.json 中暴露了大量./v2/*、./components/*、./features/*子路径导出方便按需引入。需要说明的运行环境前提package.json声明了node: 22仓库采用 pnpm 作为包管理器并在根目录通过 pnpm-workspace 与 turbo 进行多包编排。快速启动运行三个 Playground维护文档给出的启动方式分为两种进入包目录直接运行或从仓库根目录借助 Turbo 自动构建依赖。方式一进入包目录运行cd packages/api-client pnpm dev # Starts the v2 web playground (default) pnpm playground:v2:web # Same as dev — standalone web client pnpm playground:v2:app # Desktop-style app layout with full workspace pnpm playground:v2:modal # Modal overlay layout方式二仓库根目录 Turbo自动构建依赖pnpm turbo --filter scalar/api-client dev使用 Turbo 的好处在于它会自动构建scalar/api-client所依赖的 workspace 包。从 packages/api-client/package.json 的 dependencies 可以看到该包依赖了大量同仓库包scalar/blocks、scalar/components、scalar/oas-utils、scalar/sidebar、scalar/snippetz、scalar/themes、scalar/workspace-store、scalar/use-codemirror、scalar/use-toasts等首次运行时依赖较多直接跑pnpm dev前建议先完成一次构建或使用 Turbo 链路。脚本定义的实际情况AGENTS.md 中列出的playground:v2:web/playground:v2:app/playground:v2:modal是维护者推荐的可读脚本名以当前仓库为准package.json中实际定义的开发脚本为dev: vite ./playground/modal -c ./vite.config.ts即pnpm dev会直接启动 packages/api-client/playground/modal 下的 modal playground。若你想精确复现本文命令请先通过pnpm run查看当前生效的脚本列表再决定执行哪个目标。playground 的目录结构与入口如下packages/api-client/playground/modal/index.html 与 packages/api-client/playground/modal/main.tsmodal 布局的 Vite 入口main.ts中先createWorkspaceStore()并await addDocument(...)加载默认文档再调用createApiClientModal(...)挂载并open()packages/api-client/playground/test/index.ts测试用 playground 入口。开发服务器相关配置集中在 packages/api-client/vite.config.ts端口server.port 5065启动后访问http://localhost:5065代理/void: https://void.scalar.com用于在同域 cookie 场景下测试请求别名→./src、v2→./src/v2、test→./test构建以 ES 格式输出库文件cssFileName: vue-styles保留 sourcemap便于调试测试环境Vitest 使用 jsdomsetup 文件为./test/vitest.setup.ts。三种布局的差异与适用场景维护文档用一张表格清晰区分了三种布局这是理解该在哪个 playground 里测试什么的关键布局脚本描述Webpnpm playground:v2:web独立浏览器客户端。默认dev目标。单请求聚焦。Apppnpm playground:v2:app完整桌面风格布局含侧边栏、集合、环境与工作区管理。工作区相关变更在此测试。Modalpnpm playground:v2:modal以覆盖层形式打开。也可通过 api-reference playground 中对任一操作点击 Test Request 按钮来测试。三种布局的定位差异可以总结为Web 布局面向快速发一个请求的轻量场景交互链路短界面元素少适合作为请求/响应链路的回归基线App 布局是功能最全的形态侧边栏集合树、拖拽排序、环境切换、工作区workspace管理都只在此布局完整呈现因此凡涉及 workspace 状态与组织能力的改动必须在 app 布局验证Modal 布局是嵌入式的它不依赖路由器导航通过直接设置活动实体完成见下文源码分析并且会被 API Reference 的 Test Request 按钮复用——也就是说modal 不仅是独立功能还是scalar/api-reference与客户端之间的桥接层。视觉测试检查清单维护文档给出了一份逐项检查清单覆盖客户端最主要的功能区域。结合源码目录可以将其映射到具体实现模块便于在改动时快速定位受影响代码地址栏Address bar——URL 输入、方法选择器、发送按钮。对应 src/v2/blocks/scalar-address-bar-block请求编辑器Request editor——body、headers、query params、path params、认证 tabs。对应 src/v2/blocks/request-block以及code-input、data-table等编辑组件响应查看器Response viewer——状态、响应头、带语法高亮的响应体。对应 src/v2/blocks/response-block语法高亮依赖同仓库的scalar/code-highlight与scalar/use-codemirror侧边栏Sidebarapp 布局——集合树、请求组织、拖拽。对应 src/v2/components/sidebar并复用scalar/sidebar包环境Environmentsapp 布局——变量管理、环境切换。对应 src/v2/features/environments认证Auth——Bearer、Basic、API Key、OAuth 等认证表单。对应 src/v2/blocks/scalar-auth-selector-blockOAuth 流程相关辅助代码位于该块的helpers/oauth。除此之外从src/v2/features目录还可以看到两个与客户端体验强相关的功能域测试时建议一并关注Command Palettesrc/v2/features/command-palette命令面板用于快速搜索与跳转操作Searchsrc/v2/features/search基于fuse.js的搜索能力该依赖已声明在 package.json 中。各布局的测试时机如何根据变更类型选择目标维护文档给出的选择规则非常实用直接决定测试效率宽泛的 UI 变更组件、样式、布局——需要同时测试web与app。因为这类改动影响面大web 覆盖单请求链路app 覆盖完整工作区二者缺一不可请求/响应相关变更——web布局测试即可。请求与响应链路在两个布局中共享同一套 blocks 实现web 已足够作为回归基线侧边栏、集合、工作区相关变更——必须在app布局测试。这些能力只在 app 布局完整呈现Modal 集成——通过api-referenceplayground 的 Test Request 按钮或playground:v2:modal测试。因为 modal 的最终消费场景往往是嵌入在 API Reference 中。这条规则的深层原因是三种布局共享同一套blocks与features实现操作块、请求块、响应块、认证选择块均位于src/v2/blocks布局差异主要体现在外壳sidebar、workspace、overlay与导航方式上。因此请求/响应这类内核逻辑用最轻量的 web 验证即可而外壳与组织能力必须回到 app 与 modal 中验证。深入Modal 布局的源码级实现与测试验证createApiClientModal是 modal 布局的核心工厂函数实现在 src/v2/features/modal/helpers/create-api-client-modal.ts并从 src/v2/features/modal/index.ts 统一导出。几个值得关注的实现细节1. 不依赖路由器的导航方式源码注释明确说明The modal does not require a router. Instead, navigation is handled by setting active entities directly through the returnedroutefunction.modal 不需要路由器导航通过返回的route函数直接设置活动实体完成。其实现是维护一个reactive的parameters对象含path、method、example、documentSlug、isWebhook等默认实体route(payload)通过Object.assign(parameters, defaultEntities, payload)完成跳转再由resolveRouteParameters(workspaceStore, parameters)计算最终解析结果。2. 每实例独立的idPrefix源码中有一个单调递增的modalAppCount计数器为每个 modal Vue 应用生成唯一的idPrefix。原因是当 API Reference 与另一个客户端实例同页挂载时若共享前缀useId()生成的 teleport 目标 id 会重复导致 popover 弹出到隐藏实例而不可见。这个设计保证了多客户端实例共存于同一页面的场景稳定。3. 可响应的 optionsoptions参数既可以是普通对象也可以是refMaybeRefOrGetterApiClientOptions内部统一转换为optionsRef方便 React 等外部框架以响应式方式传入配置。4. 与 workspace-store 的协作modal 是 OpenAPI-only 的document计算属性会通过isOpenApiDocument类型守卫过滤AsyncAPI 文档解析为null。同时支持通过事件总线接收ui:open:client-modal事件测试用例 applies request body composition selection from the open-client-modal event 验证了该路径。测试证据单元测试文件 src/v2/features/modal/helpers/create-api-client-modal.test.ts 使用 Vitest 覆盖了以下关键行为可作为行为规格参考mountOnInitialize为true时自动挂载为false时手动挂载open可路由到指定操作path methodoptions.authentication变化时 UI 响应式更新options ref 被整体替换时 UI 同步更新updateOptions默认合并merge配置、overwritetrue时整体替换modal 关闭后改动得以保留每个 modal 实例获得唯一的 id prefix即上文第 2 点。从 Playground 到集成App 与 Modal 的挂载方式Playground 的代码本质上是真实集成的浓缩版。以 packages/api-client/playground/modal/main.ts 为参照modal 布局的挂载流程是先createWorkspaceStore()初始化 workspace store再await workspaceStore.addDocument(...)加入至少一个文档playground 中加载的是scalar/galaxy的示例 OpenAPI 文档最后调用createApiClientModal({ el, workspaceStore })并open()。playground 页面 packages/api-client/playground/modal/index.html 提供了 Show API Client 按钮点击后以{ path: /user/signup, method: post }打开指定操作。按 packages/api-client/README.md 的说明正式集成有两种形态App 形态挂载完整客户端import /style.css import { createApiClientApp } from scalar/api-client/app const el document.getElementById(scalar-client) createApiClientApp(el, { layout: web })Modal 形态紧凑覆盖层必须先初始化 workspace store 并添加文档import { createWorkspaceStore } from scalar/workspace-store/client import { createApiClientModal } from scalar/api-client/modal import /style.css const workspaceStore createWorkspaceStore() await workspaceStore.addDocument({ name: default, url: https://cdn.jsdelivr.net/npm/scalar/galaxy/dist/latest.json, }) const modal createApiClientModal({ el: document.getElementById(app), workspaceStore, options: { proxyUrl: https://proxy.scalar.com, }, }) // 立即打开 modal.open() // 或带路由打开 modal.open({ path: /user/signup, method: post }) // 已打开时导航 modal.route({ path: /me, method: get }) // 运行时合并配置 modal.updateOptions({ hideClientButton: true })createApiClientModal返回对象源码类型见 src/v2/features/modal/helpers/create-api-client-modal.ts 中的ApiClientModal包含open(payload?)打开 modal可选地导航到指定路由route(payload)导航而不切换可见性updateOptions(nextOptions, overwrite?)默认合并配置overwritetrue时整体替换mount(mountingEl?)挂载到指定元素配合mountOnInitialize: false可用于 SSR 场景modalState响应式的打开/关闭状态对象app底层的 Vue 应用实例。open与route的路由负载结构为{ path: string method: HttpMethod example?: string documentSlug?: string // 多文档场景 isWebhook?: boolean // 按 OpenAPI webhook 名称解析路径 }options配置项packages/api-client/README.md 及 src/v2/types/options.ts 中的ApiClientOptions类型支持以下键选项说明proxyUrlCORS 阻止浏览器直连时通过代理 URL 发送请求authentication预填认证凭据与默认安全方案行为baseServerURL为所有相对 server 添加统一前缀hideClientButton在基于 modal 的集成中隐藏客户端按钮hiddenClients控制展示哪些 HTTP 代码示例客户端传[]展示全部oauth2RedirectUri设置 OAuth 2.0 授权码与隐式流程的默认回调 URIservers覆盖 OpenAPI 文档中的 serverscustomFetch自定义 fetch 实现替换请求执行引擎sendRequest中的全局 fetchcaptureOAuth2Callback捕获 OAuth2 回调桌面端通过系统浏览器 loopback 完成授权时使用此外plugins选项接受ClientPlugin[]可为客户端扩展生命周期钩子、自定义 UI 组件与响应体处理。典型场景是支持非标准 Content-Type如 MessagePack的响应解码与展示responseBody处理器支持mimeTypes可通配匹配、decode、language、rawComponent、previewComponent等属性。小结围绕 packages/api-client/AGENTS.md 展开scalar/api-client 的视觉测试方法论可以浓缩为三点用 web 验证请求/响应内核、用 app 验证侧边栏与工作区组织、用 modal 验证嵌入式集成。启动 playground 只需pnpm dev默认 modal 布局或通过 Turbo 从根目录运行测试时对照地址栏、请求编辑器、响应查看器、侧边栏、环境、认证六项检查清单逐项回归涉及 modal 的改动务必同时验证 api-reference 中 Test Request 的联动入口。理解createApiClientModal的无路由器导航、唯一idPrefix与 workspace-store 协作机制后你不仅能熟练测试也能自信地基于该包进行二次集成与扩展。【免费下载链接】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），仅供参考