从 Zuplo 迁移到 Scalar把开发者门户迁离 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本文是一份面向 Zuplo 用户的迁移实战指南核心思路是把开发者门户从 Zuplo 迁到 Scalar同时把 API 网关限流、鉴权、计费等流量能力原样保留在 Zuplo。读完本文你将掌握完整的八步迁移流程——从导出 OpenAPI、上传与配置scalar.config.json到迁移自定义样式、Markdown 指南、自定义域名与重定向并理解 Scalar 在文档渲染、Mock Server、SDK 生成、Spectral 校验等环节的源码级实现原理。架构差异API 网关与旁路文档平台并不冲突Zuplo 本质上是API 网关你的 API 流量流经它的基础设施由它负责代理转发、速率限制rate limiting、认证与计费monetization并顺带提供一个开发者门户用于文档展示。Scalar 则采用完全不同的架构它旁路lives alongside你的 API不触碰任何业务流量专注文档与开发者工具。这意味着两者可以共存——继续让 Zuplo 承担网关职责同时用 Scalar 提供文档和开发者工具链你的 API 流量依旧流经 Zuplo互不干扰。把开发者门户从 Zuplo 迁到 Scalar 后你将解锁一套完整的开发者体验工具API Client支持 Windows、macOS、Linux 的现代开源 API 测试客户端对应仓库 packages/api-clientSDKs从 OpenAPI 文档生成 TypeScript、Python、Golang 等语言的类型安全客户端库Spectral Linting用 Spectral 规则校验和 lint OpenAPI 文档Mock Server根据 OpenAPI 文档启动一个功能完整的 Mock Server服务前端开发与测试对应仓库 packages/mock-server开源与自托管大部分包完全开源自托管非常容易。定价对比按用户计费 vs 按请求计费Scalar 提供更低的准入门槛——有免费层级且定价更简单而 Zuplo 的定价与网关用量挂钩PlanScalarZuploFree✓limited requestsPaid$150/mo (5 seats incl.)usage-basedEnterprisecustom pricingcustom pricing两个定价模型的本质差异Scalar 按用户计费文档平台属性Zuplo 按请求计费网关用量属性Scalar 的免费层级不依赖 API 流量适合低成本起步对以文档为核心的团队Scalar 的成本更可预测、通常更低。仓库内 documentation/guides/pricing.md 给出了更完整的计划明细可供迁移前评估Free 免费最多 3 个 API、1 个编辑席位Pro $150/月按月或 $125/月按年5 个编辑席位、最多 15 个 APIBusiness $600/月或 $500/月按年Enterprise 定制含 SLA 与迁移服务。功能对比Scalar 与 Zuplo 开发者门户FeatureScalarZuplo Developer PortalSpecification SupportOpenAPI 3.0✓✓OpenAPI 3.1✓✓OpenAPI 3.2in progressDocumentationAPI Reference✓✓API Client✓✓Unified Search✓✓Markdown Guides✓✓CustomizationCustom Domain✓✓Custom Styling (CSS)✓✓Built-in Themes11 themeslimitedRemove Powered by Branding✓enterprise-onlyCustom CSS JS✓✓Developer ToolsDesktop API Client✓SDK GenerationYes (8 languages)Mock Server✓✓Spectral Linting✓Code Snippet Generation25 languageslimitedIntegrationsGitHub Sync✓✓CLI✓✓API✓✓Framework Integrationsall frameworkslimitedOpen SourceSelf-hostable✓✓从源码结构看这份功能清单在仓库中都有对应实现桌面 API Client 位于 packages/api-clientMock Server 位于 packages/mock-server主题样式位于 packages/themes/src内含 20 余个 CSS 主题文件代码片段生成器位于 packages/snippetz。SDK 生成8 种语言随文档同步更新从你的 OpenAPI 文档生成类型安全的客户端库Scalar 支持多语言 SDK 生成LanguageStatusTypeScriptAvailablePythonAvailableGoAvailableJavaAvailablePHPAvailableRubyAvailableSwiftAvailableC#AvailableSDK 与你的 API 文档保持同步每当 OpenAPI 文档更新SDK 也会随之更新。完整的生成、构建、发布流程见 documentation/guides/sdks/getting-started.md——在 Dashboard 中上传 OpenAPI 文档、选择目标语言可一次选择多个 SDK/CLI、随后即可对生成的 SDK 进行构建、版本管理、下载、配置甚至链接 GitHub 仓库发布到包注册中心。框架集成覆盖主流技术栈Scalar 为所有主流 Web 框架提供官方集成可以轻松地把 API 文档接入任意技术栈FrameworkAvailableExpress✓Fastify✓Hono✓NestJS✓Next.js✓Nuxt✓SvelteKit✓Docusaurus✓Astro✓ASP.NET Core✓Aspire✓FastAPI✓Django Ninja✓Spring (Java)✓Docker✓这些集成全部位于仓库 integrations 目录下如 integrations/express、integrations/fastify、integrations/nestjs、integrations/dotnet/aspnetcore、integrations/fastapi 等均保持积极维护并遵循相同的配置模式因此在框架之间切换、或让 Scalar 服务多个服务时几乎零学习成本。Spectral Linting 与 API 原型验证Spectral Linting使用 Spectral 规则校验和 lint 你的 OpenAPI 文档。Spectral 规则可以与 OpenAPI 文档、JSON Schema 一起在 Registry 中管理让 API 契约在发布前就通过自动化校验。API 原型验证Mock Server根据你的 OpenAPI 文档启动一个功能完整的 Mock Server它会基于 schema 自动生成逼真的 API 响应非常适合前端开发、API 原型设计和集成测试npx scalar/cli document mock openapi.json --watch--watch让 Mock Server 监听文档变化并自动重启。除了 CLI还可以在 Docker 容器中运行或直接集成进 Node.js 应用。完整用法见 documentation/guides/mock-server/getting-started.md。从源码看Mock Server 的实现位于 packages/mock-server/src核心能力包括自动为文档中的每个路径生成端点、基于 schema 生成真实感 mock 数据、处理认证校验 OpenAPI security scheme启动时打印认证指引、按Prefer头选择响应如Prefer: code404、Prefer: examplebob并默认对请求做 OpenAPI 契约校验——请求违反契约时返回422 Unprocessable Entity与application/problemjson错误体。这正是前端联调、原型验证阶段需要的全部能力。从 Zuplo 迁移到 Scalar八步完整流程由于两个平台都是OpenAPI 原生的迁移非常直接你的 OpenAPI 文档可以原样迁移网关功能继续留在 Zuplo而文档与开发者工具交给 Scalar。Step 1从 Zuplo 导出 OpenAPIZuplo 以 OpenAPI 格式存储 API 配置。导出 OpenAPI 文档进入 Zuplo 项目 Dashboard打开项目的Routes或OpenAPI板块找到routes.oas.json文件或类似的 OpenAPI 文档下载或复制该 OpenAPI JSON/YAML 文件。[!NOTE] Zuplo 使用x-zuplo-route、x-zuplo-path等供应商扩展vendor extensions保存网关专属配置。Scalar 会忽略这些扩展但不会报错——它们只是不参与文档渲染。如果 Zuplo 中有多个 OpenAPI 文件分散在不同文件中你需要分别导出每个文件或把它们合并成单个文档。Step 2创建 Scalar 账号Scalar 提供免费层级足以完成大量工作。注册无需信用卡进入 Scalar Dashboard 注册即可。Step 3上传 OpenAPI 文档创建账号后在 Dashboard 点击Create Documentation选择Upload File上传文件或GitHub Sync如果你想把 OpenAPI 存进 Git上传从 Zuplo 导出的 OpenAPI 文件Scalar 会自动解析并渲染出你的 API Reference。如果使用 GitHub Sync可以把 OpenAPI 文件提交到仓库Scalar 会自动同步。Step 4配置 Scalar ConfigGitHub Sync 场景使用 GitHub Sync 时在仓库根目录创建scalar.config.json来配置你的文档站点。仓库根目录的 scalar.config.json 就是一个真实可参考的完整示例包含$schema、siteConfig、navigation等字段。最小可用的迁移配置如下{ $schema: https://registry.scalar.com/scalar/schemas/config, scalar: 2.0.0, siteConfig: { subdomain: name-of-your-api }, navigation: { routes: { /: { type: group, title: Your API, children: { /api: { type: openapi, url: openapi.yaml, title: API Reference } } } } } }关键字段说明$schema配置的 JSON Schema 地址用于编辑器的校验与自动补全scalar配置格式版本号siteConfig.subdomain站点在 Scalar 平台上的子域名标识navigation.routes站点路由树type: group表示分组节点type: openapi表示挂载一个 OpenAPI 文档url指向文档路径title为显示标题。自动部署分支合并进主分支时自动发布可以在 Scalar Dashboard 的项目设置中配置。Step 5迁移自定义样式如果你用 CSS 定制过 Zuplo 开发者门户可以直接把样式作为customCss传入配置或改用 Scalar 的 CSS 变量迁移。Scalar 提供丰富的主题定制能力: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); }这些 CSS 变量--scalar-font、--scalar-color-accent、--scalar-background-1、--scalar-color-1是 Scalar 主题体系的核心仓库 packages/themes/src 中的 20 余个 CSS 文件就是基于这套变量体系实现的。Scalar 还内置11 个主题可供直接作为起点default、alternate、moon、purple、solarized、bluePlanet、saturn、kepler、mars、deepSpace、laserwaveStep 6可选迁移 Markdown 指南如果 Zuplo 开发者门户里有 Markdown 指南从 Zuplo 导出 MDX 或 Markdown 内容如果使用 MDX把 JSX 组件转换成标准 MarkdownScalar 使用标准 Markdown在文档项目的Guides选项卡中添加指南或者使用 GitHub Sync 时把它们加入仓库并在scalar.config.json中引用{ navigation: { routes: { /: { type: group, title: Your 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 } } } } } }这里新增了两个关键节点类型type: group嵌套的指南分组与type: page用filepath指向仓库内的 Markdown 文件。Step 7可选把自定义域名指向 Scalar如果 Zuplo 用了自定义域名例如developers.example.com可以把它指向 Scalar在 Scalar 配置中添加自定义域名{ siteConfig: { subdomain: name-of-your-api, customDomain: developers.example.com } }把 DNS CNAME 记录指向dns.scalar.com等待几分钟 DNS 生效。更完整的域名配置说明见 documentation/guides/docs/configuration/domains.md。Step 8可选设置重定向如果已有流量进入 Zuplo 开发者门户你可能需要设置重定向以保证旧链接继续可用。Scalar 通过siteConfig.routing.redirects支持重定向{ siteConfig: { routing: { redirects: [{ from: /old-path/:wildcard, to: /new-path/:wildcard }] } } }重定向支持:wildcard通配符语法可将整段旧路径映射到新路径。仓库根目录的 scalar.config.json 中就有大量真实的重定向示例如/docs→/products可供参考。更完整的说明见 documentation/guides/docs/configuration/redirects.md。混合架构Zuplo 网关 Scalar 文档由于 Zuplo 与 Scalar 架构不同它们可以协同工作Zuplo 负责你的 API 流量限流、认证、计费等Scalar 旁路运行在你的 API 旁边文档与开发者工具。如果 OpenAPI 文档托管在 Zuplo 网关上可以直接在 Scalar 中链接它{ navigation: { routes: { /api: { type: openapi, url: https://your-zuplo-gateway.com/openapi.json, title: API Reference } } } }注意这里的url指向的是一个远程 URL而非本地文件路径。这样一来文档会自动与网关配置保持同步——Zuplo 更新 OpenAPI 文档Scalar 渲染的 API Reference 即刻反映最新契约。迁移注意事项与配套资源迁移前建议先阅读 documentation/migration/index.md了解 Scalar 迁移指南的整体原则从你已有的 OpenAPI 文档、配置文件或 Markdown 出发最终落在 Scalar 上运行无需重新创作内容或转换专有格式若你的 OpenAPI 文档需要合并或校验可配合仓库内的 packages/openapi-parser 与 packages/openapi-validator 在 CI 中先行验证确保迁移后的文档合法主题迁移可参考 documentation/themes.md 与 packages/themes 的源码实现。总结本次迁移最大的优势在于两个工具都以 OpenAPI 为根基你的核心规范可以零损失迁移。Scalar 不会替代你的网关而是与网关共存——限流、认证、计费继续由 Zuplo 承担文档、API Client、SDK 生成、Mock Server、Spectral 校验等开发者体验交给 Scalar。对于有复杂 Zuplo 实现的团队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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考