Scalar 迁移指南从 Swagger UI、Stoplight、API Hub、Stainless 等平台无缝迁移 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将现有 API 文档体系迁移到 Scalar是这篇指南的核心主题。Scalar 是开源 API 平台提供现代 REST API 客户端、美观的 API References 以及对 OpenAPI/Swagger 的一等支持本指南汇集了六条成熟的迁移路径——从 Stainless、Swagger UI、Stoplight、SmartBear API Hub、Bump.sh、Zuplo 迁入 Scalar 的具体操作。读完本文你将掌握每种场景下的导出方式、scalar.config.json配置、CLI 命令映射与 GitHub 同步/发布流程并能在不重写内容、不转换专有格式的前提下完成迁移。迁移的总体原则从你已有的东西出发Scalar 的迁移指南遵循一个明确的设计理念每条迁移路径都以你现有的资产为起点——OpenAPI 文档、配置文件、一文件夹 Markdown——并以它在 Scalar 上运行为终点。你不需要重新撰写内容也不需要先把内容转换成专有格式。凡是无法原样带过去的东西指南会明确说明而不是含糊带过。这一理念在代码层面同样成立Scalar 的 API References 直接消费标准 OpenAPI 文档见 packages/api-reference 的测试与 playground 中对openapi.json/openapi.yaml的加载CLI 的document与registry命令族则围绕 OpenAPI 文档的校验、格式化、打包、升级与发布构建了完整的工具链见 packages/cli 文档 与 packages/void-server。仓库中 documentation/migration 目录下的六份指南分别覆盖以下平台迁移来源对应指南核心场景Stainlessstainless.md导入stainless.ymlSDK 命名空间、方法名、分页策略原样保留Swagger UIswagger-ui.md保留 OpenAPI 文档换用内置 API 客户端、搜索与主题Stoplightstoplight.mdAPI References 与 Markdown 指南整体迁移兼容 Design-first / Code-first 工作流SmartBear API Hubapi-hub.md用单个 Scalar 项目替代 API Hub 的 Design、Portal、Explore 三件套Bump.shbump.md迁移 OpenAPI 文档并说明 Bump.sh 目前仍占优势的领域Zuplozuplo.md迁出开发者门户同时保留 Zuplo API 网关原样不动如果你还在决策阶段可以参阅 comparison guides其中逐特性对比了 Scalar 与各替代方案。若你正在迁出 StainlessThe Stainless wind-down write-up 详细说明了背景、stainless.yml如何映射到其他生成器以及 OpenAPI Generator、Speakeasy、Fern、APIMatic、liblab 各自更合适的场景。从 Swagger UI 迁移分钟级替换OpenAPI 文档零改动Swagger UI 自 2011 年以来一直是渲染 OpenAPI 文档使用最广泛的工具生态庞大。Scalar 的 API Reference 是它的现代替代品在与你现有 OpenAPI 文档保持完全兼容的同时提供了更精致的开发者体验并解锁两个附加能力内嵌在 API Reference 中的现代开源 API 测试客户端以及开箱即用的即时搜索。为什么要迁移现代 UI/UX更干净直观的界面开箱即用即美观响应式布局、支持深色模式大 API 导航体验更好。更好的性能基于现代 Web 技术构建针对性能优化大型 OpenAPI 文档渲染更快数百个端点的界面依旧流畅。交互式 API 客户端相比 Swagger UI 的 Try it outScalar 内置客户端支持环境变量、请求历史、25 语言的代码片段生成以及可选的桌面应用。深度定制11 个内置主题 广泛的自定义 CSS从颜色、字体到侧边栏布局与组件间距均可调整。特性对比特性ScalarSwagger UI核心能力OpenAPI 3.0✓✓OpenAPI 3.1✓✓OpenAPI 3.1.2✓OpenAPI 3.2进行中暂无计划Swagger 2.0✓✓Try It Out / 测试请求✓简单实现多文档✓✓用户界面现代布局✓经典Swagger 风格布局✓✓深色模式✓内置主题11 个自定义 CSS✓✓侧边栏导航✓✓搜索✓需插件代码片段代码片段生成25 语言有限自定义代码示例✓认证OAuth 2.0✓✓API Key✓✓持久化认证凭据✓✓预填充认证凭据✓通过 hooks集成React 组件✓✓Vue 组件✓高级特性CORS 代理✓快速分享✓桌面 API 客户端✓基本 HTML 迁移多数情况下你可以在几分钟内完成替换同时保持现有 OpenAPI 文档不变。Swagger UI 的典型嵌入方式!doctype html html head titleSwagger UI/title link relstylesheet hrefhttps://unpkg.com/swagger-ui-dist/swagger-ui.css / /head body div idswagger-ui/div script srchttps://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js/script script SwaggerUIBundle({ url: /openapi.json, dom_id: #swagger-ui, }) /script /body /html对应的 Scalar API Reference 写法!doctype html html head titleAPI 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 script Scalar.createApiReference(#app, { url: /openapi.json, }) /script /body /html配置项映射常见 Swagger UI 选项到 Scalar 的映射关系如下Swagger UIScalarurlurlspeccontenturlssourcesdom_idcreateApiReference()的第一个参数deepLinking默认启用displayOperationIdshowOperationId: truedefaultModelsExpandDepth: -1hideModels: truedefaultModelExpandDepthexpandAllModelSections: truedocExpansion: nonedefaultOpenAllTags: false默认docExpansion: listdefaultOpenAllTags: false默认docExpansion: fulldefaultOpenAllTags: truefilter搜索默认启用filter: falsehideSearch: truetryItOutEnabled默认启用supportedSubmitMethods: []hideTestRequestButton: trueoperationsSorter: alphaoperationsSorter: alphaoperationsSorter: methodoperationsSorter: methodtagsSorter: alphatagsSorter: alphapersistAuthorizationpersistAuth: true主题与样式迁移如果偏好传统的 Swagger UI 布局Scalar 提供了经典布局选项Scalar.createApiReference(#app, { url: /openapi.json, layout: classic, })内置主题包括default、alternate、moon、purple、solarized、bluePlanet、saturn、kepler、mars、deepSpace、laserwave。切换主题Scalar.createApiReference(#app, { url: /openapi.json, theme: moon, })品牌化定制通过覆盖 CSS 变量实现style :root { --scalar-font: Your Font, sans-serif; --scalar-color-accent: #0a85d1; } .dark-mode { --scalar-background-1: #1a1a1a; --scalar-color-1: rgba(255, 255, 255, 0.9); } .light-mode { --scalar-background-1: #ffffff; --scalar-color-1: #121212; } /styleSwagger UI 没有的独有特性特性说明proxyUrl通过代理服务器规避 CORS 问题hiddenClients控制展示哪些代码片段语言defaultHttpClient设置默认代码片段语言searchHotKey自定义搜索键盘快捷键baseServerURL为所有相对服务器 URL 添加前缀pathRouting使用基于路径的路由替代基于 hash 的路由onBeforeRequest发送前执行推荐直接修改requestBuilder见 configuration.mdauthentication预填充认证凭据Scalar 还提供了覆盖几乎所有主流语言与框架的集成例如仓库 integrations 下的 Express、Fastify、Hono、NestJS、Next.js、Nuxt、SvelteKit、Docusaurus、Astro、ASP.NET Core、FastAPI、Django Ninja 等官方集成。从 Stoplight 迁移Design-first 与 Code-first 双工作流Stoplight 在被 SmartBear 收购前曾是挑战臃肿企业方案的 黑马如今大量团队正在寻找现代替代方案。Scalar 与 Stoplight 在特性与工作流上的相似性使它成为自然的选择从 OpenAPI 生成交互式 API Reference 文档、支持 Markdown 指南、同时适配 Design-first 与 Code-first 工作流、内置团队协作、支持自定义域名/主题/Logo、可托管或作为 Web/React 组件嵌入。Scalar 的额外优势包括灵活的 SaaS 定价免费层即可起步Pro 计划 $150/月含 5 个编辑器席位。开源完全开源、可自托管而 Stoplight 多年前已停止提供自托管。内置 API 客户端API Reference 内集成了 API 客户端用户可直接从文档发送测试请求。迁移流程总览迁移 OpenAPI 文档关联你的 Git 仓库确认新 API 文档的观感可选迁移 Markdown 主题与指南可选迁移自定义 lint 规则集可选将自定义域名指向 Scalar可选配置旧 Stoplight 文档到新 Scalar 文档的重定向Design-first 与 Code-first 的适配无论你的团队用代码注解/注释、DSL如 RSwag还是日益流行的 OpenAPI 感知框架生成 OpenAPI流程大体一致生成的文档通过构建脚本或 CI 提交到 GitScalar 可以直接从 Git 读取这些已提交的 OpenAPI 与 Markdown 内容。如果 OpenAPI 由Stoplight CLI无 Git驱动生成可以直接改用 Scalar CLI 将文档推送到 Registry或并行运行一段时间观察效果。Code-first团队如果使用 Stoplight Studio 编辑器Scalar 的 Editor 界面可作同等用途修改后推送到 Registry或同步回 Git。Registry 让工作流中的其他工具获取最新 OpenAPI 或锁定到特定版本。Step 1创建免费 Scalar 账户Scalar 有免费层无需信用卡即可注册。Step 2把 OpenAPI 引入 ScalarStoplight 项目有三种形态Web Projects、Git Projects、Local Projects。指南建议统一转换为 Git 项目。Git Projects迁移一个 Stoplight Git Project 只需为 Scalar 启用 GitHub Sync——Stoplight 本质上是从 Git 仓库推拉Scalar 同样内置支持。在 dashboard 点击Create Documentation选择GitHub Sync挑选组织与仓库点击Link Repository完成关联。默认分支main之外的docs分支或v3版本分支都可以在设置中调整发布后默认私有不用担心内容提前泄露。Web Projects 导出在项目 studio 页面通过下拉菜单选择Download project ZIP导出全部 OpenAPI 与文档若只要 OpenAPI 文档可在文档页点击Export并选择Bundled确保跨文件的$ref引用被打包进去。随后把导出内容放入 Git 仓库再走上面的 Git Sync 流程。Step 3配置 scalar.config.json在仓库根目录创建scalar.config.json声明 OpenAPI 文档与指南的位置{ $schema: https://registry.scalar.com/scalar/schemas/config, scalar: 2.0.0, siteConfig: { subdomain: name-of-your-api }, navigation: { routes: { /: { type: group, title: Train Travel API, children: { /guides: { type: group, title: Guides, children: { getting-started: { type: page, filepath: docs/getting-started.md, title: Getting Started } } }, /api: { type: openapi, url: openapi.yaml, title: API Reference } } } } } }在 Scalar Dashboard 的项目设置中可配置自动部署所选分支合并后自动发布。仓库根目录的真实 scalar.config.json 展示了更完整的结构除了siteConfig.subdomain、customDomain还包含head脚本与样式、footer、logo、rss以及大量routing.redirects重定向规则——这正是迁移旧站点时管理存量链接的实践样本。Stoplight 侧边栏转换Stoplight 的toc.json定义了侧边栏内容。例如{ items: [ { type: item, title: Getting Started, uri: docs/getting-started.md }, { type: item, title: Hello World, uri: docs/hello-world.md } ] }转换只需三步type: item→type: pageuri→filepath保留title字段转换后的结果合并进scalar.config.json的navigation.routes{ $schema: https://registry.scalar.com/scalar/schemas/config, scalar: 2.0.0, siteConfig: { subdomain: name-of-your-api }, navigation: { routes: { /: { type: group, title: Train Travel API, children: { /guides: { type: group, title: Guides, children: { getting-started: { type: page, filepath: docs/getting-started.md, title: Getting Started }, hello-world: { type: page, filepath: docs/hello-world.md, title: Hello World } } }, /api: { type: openapi, url: openapi.yaml, title: API Reference } } } } } }提交并推送该文件后若启用了自动部署分支合并后 Deployments 会出现新条目。Step 4审查新文档点击部署记录获取项目文档 URL形如https://name-of-your-api.apidocumentation.com页面会展示 Guides 与各 OpenAPI Reference 两个区块含多个 OpenAPI 文档的项目会在顶部导航逐一列出。每个端点都带交互式 API 控制台可以随意点击体验。Step 5可选导出 Spectral 规则集Spectral 是 Stoplight 多年前从其他流行 OpenAPI linter 派生出的开源工具默认报告 OpenAPI 文档是否有效、有无语法错误或非法关键字。Scalar 支持 Spectral因此在 Scalar Editor 中会看到相同的错误与警告。若你使用自定义 Spectral 规则集多为 API 治理团队用于保证跨 API 一致性在 Stoplight Studio 中点击Export Spectral File导出。注意带自定义函数的规则无法生效需要注释掉这些规则。Step 6可选更新自定义域名使用自定义域名如developers.acme.com指向 Stoplight 的团队可在scalar.config.json中配置自定义域名{ siteConfig: { subdomain: name-of-your-api, customDomain: docs.example.com } }然后在 DNS 侧把 CNAME 从旧的 Stoplight 记录改为指向dns.scalar.com几分钟后生效。详见 domains 配置。Step 7可选添加重定向若 Stoplight 文档有大量存量流量可在scalar.config.json中用siteConfig.routing.redirects保持旧链接可用{ siteConfig: { routing: { redirects: [{ from: /docs/stoplight-project/10a1321b3-:wildcard, to: /scalar/scalar-registry/github-actions }] } } }使用自定义域名时旧路径会自动传递到 Scalar因此重定向可以精确把旧路径指向新路径。详见 redirects 配置。小结由于双方本质上都是 OpenAPI 驱动的核心规范可以干净迁移。多数团队可在数小时到数天内完成迁移取决于项目与 API 数量大型企业视 API 生态复杂度略长。从 SmartBear API Hub 迁移一个项目替代三件套SmartBear API Hub前称 SwaggerHub由 Design、Portal、Explore 三部分组成。Scalar 是这三者的直接替代品并具备相同的能力集中的 OpenAPI/Swagger 文档编辑协作、可交互可定制可发布的 API Reference 构建器、自定义域名/主题/Logo、内置本地优先local-first的 API 客户端。Scalar 免费起步Pro 计划 $150/月含 5 个编辑器席位自定义域名、GitHub Sync 等属于 Pro同时开源可自托管。从 API Hub Design 迁移进入 API Hub Design 找到要导出的 API在编辑器页面右上角点击Export选择JSON Unresolved保留指向其他文档的$ref值或JSON Resolved全部内联。然后在 Scalar 注册并创建新的文档项目进入项目的References标签点击Upload File上传导出的 JSON 即可文档立即可编辑、预览与发布。从 API Hub Portal 迁移API Hub Portal 用于发布 OpenAPI 的交互版本与 Markdown 指南。在 Scalar 中无需切换到另一个产品点击文档项目右上角的Publish按钮设置域名、元数据等后再次点击Publish即可部署站点。添加指南同样简单在文档项目的Guides标签页添加/编辑页面编辑器支持 Markdown可直接从 API Hub Portal 复制粘贴文档。定制方面点击Customize即可编辑 header、Logo、样式、footer、版本、代码与配置。可选使用 GitHub Sync scalar.config.json若希望像 API Hub Portal 的版本控制一样通过 Git 管理文档可使用 GitHub Sync在仓库根目录创建scalar.config.json结构与上文相同并在 Dashboard 项目设置中配置自动部署分支合并到主分支时发布。从 API Hub Explore 迁移Scalar 的 API 客户端是 API Hub Explore 的直接替代品。在 API Reference 中点击Test Request即可获得客户端版本或直接使用 API client 页面 / 桌面版。与 API Hub Explore 一样可把现有 API 文档导入 API 客户端批量建立端点用于测试随后修改、发送请求、新增路由方便地探索与调试 API。Registry 功能见 guides/registry则对应 API Hub Explore 的 Link APIs from Design 特性。从 Stainless 迁移stainless.yml 直读SDK 用户零破坏2026 年 5 月Stainless 宣布加入 Anthropic 并关停全部托管产品包括 SDK 生成器新注册、新项目与新 SDK 同步停止。对已有客户而言已生成的 SDK 继续可用Stainless 明确表示你拥有已生成的代码停止的是重新生成——下次 API 变更时一切不再更新。Scalar 将迁移建立在一条核心原则上你不应重写任何内容。把 OpenAPI 文档和stainless.yml交给 Scalar它直接从你已有的配置生成。为什么配置文件比规范更重要OpenAPI 文档从来不是离开 Stainless 的难点——它属于你、可移植、任何生成器都能读取。难点在于stainless.yml它的resources块承载了真正的设计决策——哪些操作成为哪些 SDK 命名空间、每个方法叫什么、每个列表端点采用哪种分页方案、包在各语言里叫什么名字。这些都无法在 OpenAPI 中表达。只依据规范重新生成你会得到另一个SDK新的命名空间、新的方法名对每个已安装你包的用户都是一次破坏性变更。因此 Scalar 直接读取stainless.yml资源、方法、子资源、模型、分页方案与各语言包名全部原样保留用户已经写好的调用点继续工作。在 dashboard 中创建新 SDK 时选择Import config并上传stainless.ymlCLI 同样支持。五步迁移导出 OpenAPI 文档注意若使用了 Stainless 的openapi.transforms仓库中的文档可能不是 Stainless 实际生成所用的文档应取转换后的输出保证两个生成器看到相同输入。x-stainless-*扩展可放心保留——Scalar 忽略它不认识的扩展。取你的stainless.yml它在你的仓库中有版本控制原样复制即可无需转换、剥离或先翻译成 Scalar 格式。导入 Scalar创建新 SDK选择Import config同时上传 OpenAPI 文档与stainless.yml。Scalar 读取配置、映射到自己的生成器产出目标语言的 SDK。发布前验证对比生成的api.md与现有 SDK 的api.md——两者都按资源分组列出每个方法diff 能立即告诉你公共 API 表面是否完整。重点检查嵌套子资源上的方法名列表端点的分页尤其自定义 cursor客户端类名与用户传凭据的环境变量。从你自己的仓库发布生产仓库本就属于你npm、PyPI、Maven、RubyGems 包也是。迁移不改变包名与注册表用户继续安装今天安装的东西。需要调整的是卸载 Stainless GitHub App、接管.github/workflows中的发布工作流、把注册表 token 指向 Scalar 的发布流程。Scalar 通过向你的仓库发起 pull request 来发布发布始终可审查。自定义代码的处理如果你编辑过生成文件这些编辑是仓库中的普通提交——Stainless 通过语义三方合并应用它们因此它们与生成代码交错存放而非独立补丁集。重新生成前先识别哪些文件带有手写修改Scalar 支持自定义代码提前知道要保留哪些文件会让迁移顺畅得多。Scalar 生成的效果以下来自公开的 Warp SDK 的真实生成 TypeScriptimport WarpAPI from warp-hr; const client new WarpAPI({ apiKey: process.env[API_KEY], // defaults to the API_KEY env var }); const list await client.customWorkerFields.list();错误是类型化的status 集由你的规范生成import { APIError } from warp-hr; try { const list await client.customWorkerFields.list(); } catch (err) { if (err instanceof APIError) { console.log(err.status, err.name, err.headers); } throw err; }输出对 Stainless 用户来说会很熟悉资源命名空间方法、类型化错误、自动分页、支持Retry-After的重试并且除非启用需要依赖的功能否则零运行时依赖Warp 包dependencies: {}。文档平台Docs Platform怎么办Stainless 的文档平台是 Astro 项目仓库位于stainless-sdksGitHub 组织下而非你的名下。其官方建议是 fork 出来并自行承担 CI、部署、域名与运维。若不想自建Scalar Docs 用同一份 OpenAPI 文档渲染 API Reference并支持 Markdown/MDX 指南配合scalar.config.json控制导航与主题。你无论如何都能保留的东西Stainless 明确表示已生成的 SDK 归你所有可任意修改扩展。因此没有任何截止日会破坏已发布的内容问题只在于下次 API 变更时会发生什么。相关全景分析见 Stainless wind-down write-up。从 Bump.sh 迁移CLI 命令映射对照表Bump.sh 是同时支持 OpenAPI 与 AsyncAPI 的现代 API 文档平台。迁入 Scalar 后可解锁跨 Windows/macOS/Linux 的开源 API 客户端、TypeScript/Python/Go 等语言的类型安全 SDK 生成、Spectral 规则校验、以及从 OpenAPI 文档启动的 Mock Server。需要注意的是如果 API 变更检测或 AsyncAPI 支持是组织的关键需求Bump.sh 目前在这些领域仍有优势——Scalar 尚未提供这些特性但两者已在路线图或进行中。定价对照计划ScalarBump.shFree✓✗Starter$150/moPro含 5 席位$50/monthBasicTeam$600/moBusiness10 席位$250/monthProEnterprise自定义定价自定义定价Scalar 提供免费计划而 Bump.sh 没有Bump.sh 对每个计划的文档数与用户数有硬性限制Scalar 则采用随 API 规模伸缩的用量定价。特性对比要点规范支持OpenAPI 双方都支持AsyncAPI 与 OpenAPI Overlays 在 Bump.sh 已支持Scalar 分别处于进行中与路线图。文档发布API Reference、API Registry、统一搜索、Try-it-out 双方都有自动 Changelog 在 Bump.sh 已支持、Scalar 在路线图。发布管理Diff破坏性变更检测Bump.sh 已支持、Scalar 在路线图Previews、回滚、手动发布管理双方都有。品牌定制自定义域名、Logo/颜色/favicon/meta 图、自定义 CSS JS 双方都有移除 Powered by 品牌 Scalar 全计划可用。集成CLI、API、GitHub Action 发布、PR 评论双方都有Slack 通知与 API 变更自定义 Webhook 在 Bump.sh 已支持、Scalar 在路线图。使用 CLI 迁移Bump CLI → Scalar CLI通过 CLI 迁移通常更直接。包bump-cli→scalar/cli。命令Bump.shScalarbump deploy [file]scalar registry publish [file]bump preview [file]scalar document serve [file]bump preview --live [file]scalar document serve --watch [file]bump diff即将推出bump overlay即将推出选项Bump.shScalar--doc slug--slug slug--hub slug--namespace namespace--token token先用scalar auth login --token token--branch branch--version version环境变量BUMP_TOKEN对应scalar auth login --token SCALAR_API_KEY。GitHub Actions把- uses: bump-sh/github-actionv1 with: doc: my-doc token: ${{ secrets.BUMP_TOKEN }} file: api.yaml替换为- run: npx scalar/cli auth login --token ${{ secrets.SCALAR_API_KEY }} - run: npx scalar/cli registry publish api.yaml --namespace my-team --slug my-doc认证方式把每次命令携带 token 改为一次性登录# 之前每条命令都要 token bump deploy api.yaml --token $TOKEN # 之后登录一次然后发布 scalar auth login --token $TOKEN scalar registry publish api.yaml --namespace my-team --slug my-docScalar 独有的附加命令Bump 无对应物但可能有用命令说明scalar document lint [file]用 Spectral 规则校验scalar document mock [file]启动 mock serverscalar document bundle [file]解析所有$ref引用scalar document format [file]格式化 OpenAPI 文档scalar document upgrade [file]升级到 OpenAPI 3.1这些document子命令在 packages/void-serverCLI 的后端服务实现与 packages/cli 文档 中均有对应实现与说明。从 Zuplo 迁移只搬开发者门户网关原地不动Zuplo 是 API 网关你的流量流经其基础设施它负责代理、限流、认证与变现也提供开发者门户。Scalar 采用不同思路在 API 旁边共存、不触碰你的流量专注文档与开发者工具。迁出 Zuplo 开发者门户后解锁跨平台 API 客户端、SDK 生成、Spectral 校验、Mock Server以及开源可自托管。两者用途不同完全可以搭配使用——保留 Zuplo 做网关限流、认证、变现用 Scalar 做文档与开发者工具。定价与特性要点Scalar 有免费层不依赖 API 流量付费 $150/mo 含 5 席位用户制Zuplo 为用量制请求制。特性方面Scalar 独有的包括桌面 API 客户端、8 语言 SDK 生成、Spectral linting、25 语言代码片段生成、11 个内置主题、全框架集成双方都有的包括 API Reference、API Client、统一搜索、Markdown 指南、GitHub Sync、CLI、API、Mock Server。迁移步骤从 Zuplo 导出 OpenAPI进入项目 dashboard 的Routes或OpenAPI区找到routes.oas.json或类似文件下载。Zuplo 使用x-zuplo-route、x-zuplo-path等厂商扩展承载网关配置Scalar 会忽略这些扩展但不会出错。若 Zuplo 中 OpenAPI 分散在多个文件需要分别导出或合并为单个文档。创建 Scalar 账户免费层即可无需信用卡。上传 OpenAPIdashboard 中点击Create Documentation选择Upload File或GitHub Sync上传后 Scalar 自动解析并展示 API Reference。配置 scalar.config.json使用 GitHub Sync 时与上文结构一致声明 OpenAPI 与指南路径配置自动部署。迁移自定义样式把 Zuplo 门户的 CSS 作为customCss传入或用 CSS 变量迁移:root { --scalar-font: Your Font, sans-serif; --scalar-color-accent: #your-color; --scalar-background-1: #ffffff; --scalar-color-1: #121212; } .dark-mode { --scalar-background-1: #1a1a1a; --scalar-color-1: rgba(255, 255, 255, 0.9); }11 个内置主题default、alternate、moon、purple、solarized、bluePlanet、saturn、kepler、mars、deepSpace、laserwave可作起点。可选迁移 Markdown 指南导出 Zuplo 的 MDX/Markdown 内容若用 MDX把 JSX 组件转成标准 MarkdownScalar 使用标准 Markdown通过Guides标签页添加或放入仓库后在scalar.config.json中引用type: pagefilepath。可选指向自定义域名siteConfig中添加customDomainDNS 的 CNAME 指向dns.scalar.com等待传播生效。详见 domains 配置。可选设置重定向{ siteConfig: { routing: { redirects: [{ from: /old-path/:wildcard, to: /new-path/:wildcard }] } } }详见 redirects 配置。Zuplo 网关与 Scalar 文档协同由于架构不同两者天然互补Zuplo 处理流量Scalar 在旁提供文档。若 OpenAPI 文档托管在 Zuplo 网关上可以直接在scalar.config.json中链接它{ navigation: { routes: { /api: { type: openapi, url: https://your-zuplo-gateway.com/openapi.json, title: API Reference } } } }这样文档会随网关配置自动保持同步。迁移的共性模式与决策清单纵观六条路径可以提炼出迁移到 Scalar 的几个共性模式导出标准 OpenAPI所有平台都支持导出 OpenAPI JSON/YAML注意选择 Resolved/Bundled 以保留或展开$ref。上传或 Git 同步小项目用Upload File直接上传需要版本控制与自动发布则用GitHub Sync在仓库根目录放scalar.config.json参考仓库根目录的真实 scalar.config.json 样例。迁移指南与侧边栏Markdown 指南直接复制进GuidesStoplight 的toc.json可按type/uri→type/filepath规则转换。迁移 lint 与主题Spectral 规则集可继续使用自定义函数除外品牌化通过 CSS 变量与 11 个内置主题完成。域名与重定向CNAME 指向dns.scalar.com用siteConfig.routing.redirects保住存量链接。发布dashboard 配置自动部署或用 CLIscalar auth loginscalar registry publish接入 CI/CD。决策时请记住各指南中明确提到的边界Bump.sh 在 AsyncAPI、API 变更检测、自动 Changelog 上仍有优势Stainless 迁移中targets: terraform与targets: sql无 Scalar 对应物openapi.transforms需在上游处理Zuplo 迁移只涉及开发者门户网关可原样保留。这些坦诚的说明详见 documentation/migration 下各指南能帮你判断每条路径是否适合你的团队。【免费下载链接】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），仅供参考