首页
/ Scalar 迁移指南：从 Swagger UI、Stoplight、API Hub、Stainless 等平台无缝迁移 API 文档

Scalar 迁移指南：从 Swagger UI、Stoplight、API Hub、Stainless 等平台无缝迁移 API 文档

2026-09-13 18:16:54作者：裘旻烁
scalar
Scalar 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 目录下的六份指南，分别覆盖以下平台：

迁移来源 对应指南 核心场景
Stainless stainless.md 导入 stainless.yml，SDK 命名空间、方法名、分页策略原样保留
Swagger UI swagger-ui.md 保留 OpenAPI 文档，换用内置 API 客户端、搜索与主题
Stoplight stoplight.md API References 与 Markdown 指南整体迁移，兼容 Design-first / Code-first 工作流
SmartBear API Hub api-hub.md 用单个 Scalar 项目替代 API Hub 的 Design、Portal、Explore 三件套
Bump.sh bump.md 迁移 OpenAPI 文档，并说明 Bump.sh 目前仍占优势的领域
Zuplo zuplo.md 迁出开发者门户，同时保留 Zuplo API 网关原样不动

如果你还在决策阶段，可以参阅 comparison guides，其中逐特性对比了 Scalar 与各替代方案。若你正在迁出 Stainless，The 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 out"，Scalar 内置客户端支持环境变量、请求历史、25+ 语言的代码片段生成，以及可选的桌面应用。
  • 深度定制：11 个内置主题 + 广泛的自定义 CSS，从颜色、字体到侧边栏布局与组件间距均可调整。

特性对比

特性 Scalar Swagger 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>
    <title>Swagger UI</title>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="https://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>
    <title>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>
    <script>
      Scalar.createApiReference('#app', {
        url: '/openapi.json',
      })
    </script>
  </body>
</html>

配置项映射

常见 Swagger UI 选项到 Scalar 的映射关系如下：

Swagger UI Scalar
url url
spec content
urls sources
dom_id createApiReference() 的第一个参数
deepLinking 默认启用
displayOperationId showOperationId: true
defaultModelsExpandDepth: -1 hideModels: true
defaultModelExpandDepth expandAllModelSections: true
docExpansion: 'none' defaultOpenAllTags: false（默认）
docExpansion: 'list' defaultOpenAllTags: false（默认）
docExpansion: 'full' defaultOpenAllTags: true
filter 搜索默认启用
filter: false hideSearch: true
tryItOutEnabled 默认启用
supportedSubmitMethods: [] hideTestRequestButton: true
operationsSorter: 'alpha' operationsSorter: 'alpha'
operationsSorter: 'method' operationsSorter: 'method'
tagsSorter: 'alpha' tagsSorter: 'alpha'
persistAuthorization persistAuth: 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;
  }
</style>

Swagger UI 没有的独有特性

特性 说明
proxyUrl 通过代理服务器规避 CORS 问题
hiddenClients 控制展示哪些代码片段语言
defaultHttpClient 设置默认代码片段语言
searchHotKey 自定义搜索键盘快捷键
baseServerURL 为所有相对服务器 URL 添加前缀
pathRouting 使用基于路径的路由替代基于 hash 的路由
onBeforeRequest 发送前执行；推荐直接修改 requestBuilder（见 configuration.md）
authentication 预填充认证凭据

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 客户端，用户可直接从文档发送测试请求。

迁移流程总览

  1. 迁移 OpenAPI 文档
  2. 关联你的 Git 仓库
  3. 确认新 API 文档的观感
  4. （可选）迁移 Markdown 主题与指南
  5. （可选）迁移自定义 lint 规则集
  6. （可选）将自定义域名指向 Scalar
  7. （可选）配置旧 Stoplight 文档到新 Scalar 文档的重定向

Design-first 与 Code-first 的适配

无论你的团队用代码注解/注释、DSL（如 RSwag），还是日益流行的 OpenAPI 感知框架生成 OpenAPI，流程大体一致：生成的文档通过构建脚本或 CI 提交到 Git，Scalar 可以直接从 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 引入 Scalar

Stoplight 项目有三种形态：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"
    }
  ]
}

转换只需三步：

  1. type: item → type: page
  2. uri → filepath
  3. 保留 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.yml，CLI 同样支持。

五步迁移

  1. 导出 OpenAPI 文档：注意若使用了 Stainless 的 openapi.transforms，仓库中的文档可能不是 Stainless 实际生成所用的文档，应取转换后的输出，保证两个生成器看到相同输入。x-stainless-* 扩展可放心保留——Scalar 忽略它不认识的扩展。
  2. 取你的 stainless.yml：它在你的仓库中有版本控制，原样复制即可，无需转换、剥离或先翻译成 Scalar 格式。
  3. 导入 Scalar：创建新 SDK，选择 Import config，同时上传 OpenAPI 文档与 stainless.yml。Scalar 读取配置、映射到自己的生成器，产出目标语言的 SDK。
  4. 发布前验证：对比生成的 api.md 与现有 SDK 的 api.md——两者都按资源分组列出每个方法，diff 能立即告诉你公共 API 表面是否完整。重点检查：嵌套子资源上的方法名；列表端点的分页（尤其自定义 cursor）；客户端类名与用户传凭据的环境变量。
  5. 从你自己的仓库发布：生产仓库本就属于你，npm、PyPI、Maven、RubyGems 包也是。迁移不改变包名与注册表，用户继续安装今天安装的东西。需要调整的是：卸载 Stainless GitHub App、接管 .github/workflows 中的发布工作流、把注册表 token 指向 Scalar 的发布流程。Scalar 通过向你的仓库发起 pull request 来发布，发布始终可审查。

自定义代码的处理

如果你编辑过生成文件，这些编辑是仓库中的普通提交——Stainless 通过语义三方合并应用它们，因此它们与生成代码交错存放，而非独立补丁集。重新生成前，先识别哪些文件带有手写修改；Scalar 支持自定义代码，提前知道要保留哪些文件会让迁移顺畅得多。

Scalar 生成的效果

以下来自公开的 Warp SDK 的真实生成 TypeScript：

import 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-sdks GitHub 组织下而非你的名下。其官方建议是 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 尚未提供这些特性，但两者已在路线图或进行中。

定价对照

计划 Scalar Bump.sh
Free ✓ ✗
Starter $150/mo（Pro，含 5 席位） $50/month（Basic）
Team $600/mo（Business，10 席位） $250/month（Pro）
Enterprise 自定义定价 自定义定价

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.sh Scalar
bump 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.sh Scalar
--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-action@v1
  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-doc

Scalar 独有的附加命令（Bump 无对应物，但可能有用）：

命令 说明
scalar document lint [file] 用 Spectral 规则校验
scalar document mock [file] 启动 mock server
scalar document bundle [file] 解析所有 $ref 引用
scalar document format [file] 格式化 OpenAPI 文档
scalar document upgrade [file] 升级到 OpenAPI 3.1

这些 document 子命令在 packages/void-server（CLI 的后端服务实现）与 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。

迁移步骤

  1. 从 Zuplo 导出 OpenAPI：进入项目 dashboard 的 Routes 或 OpenAPI 区，找到 routes.oas.json（或类似文件）下载。Zuplo 使用 x-zuplo-route、x-zuplo-path 等厂商扩展承载网关配置，Scalar 会忽略这些扩展但不会出错。若 Zuplo 中 OpenAPI 分散在多个文件，需要分别导出或合并为单个文档。
  2. 创建 Scalar 账户：免费层即可，无需信用卡。
  3. 上传 OpenAPI：dashboard 中点击 Create Documentation，选择 Upload File 或 GitHub Sync，上传后 Scalar 自动解析并展示 API Reference。
  4. 配置 scalar.config.json（使用 GitHub Sync 时）：与上文结构一致，声明 OpenAPI 与指南路径，配置自动部署。
  5. 迁移自定义样式：把 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）可作起点。

  1. （可选）迁移 Markdown 指南：导出 Zuplo 的 MDX/Markdown 内容；若用 MDX，把 JSX 组件转成标准 Markdown（Scalar 使用标准 Markdown）；通过 Guides 标签页添加，或放入仓库后在 scalar.config.json 中引用（type: page + filepath）。
  2. （可选）指向自定义域名：siteConfig 中添加 customDomain，DNS 的 CNAME 指向 dns.scalar.com，等待传播生效。详见 domains 配置。
  3. （可选）设置重定向：
{
  "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 的几个共性模式：

  1. 导出标准 OpenAPI：所有平台都支持导出 OpenAPI JSON/YAML（注意选择 Resolved/Bundled 以保留或展开 $ref）。
  2. 上传或 Git 同步：小项目用 Upload File 直接上传；需要版本控制与自动发布则用 GitHub Sync，在仓库根目录放 scalar.config.json（参考仓库根目录的真实 scalar.config.json 样例）。
  3. 迁移指南与侧边栏：Markdown 指南直接复制进 Guides；Stoplight 的 toc.json 可按 type/uri → type/filepath 规则转换。
  4. 迁移 lint 与主题：Spectral 规则集可继续使用（自定义函数除外）；品牌化通过 CSS 变量与 11 个内置主题完成。
  5. 域名与重定向：CNAME 指向 dns.scalar.com，用 siteConfig.routing.redirects 保住存量链接。
  6. 发布：dashboard 配置自动部署，或用 CLI（scalar auth login + scalar registry publish）接入 CI/CD。

决策时请记住各指南中明确提到的边界：Bump.sh 在 AsyncAPI、API 变更检测、自动 Changelog 上仍有优势；Stainless 迁移中 targets: terraform 与 targets: sql 无 Scalar 对应物，openapi.transforms 需在上游处理；Zuplo 迁移只涉及开发者门户，网关可原样保留。这些坦诚的说明（详见 documentation/migration 下各指南）能帮你判断每条路径是否适合你的团队。

scalar
Scalar 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
登录后查看全文

相关内容推荐

1 Scalar Docs URL 重定向机制详解：scalar.config.json 中 siteConfig.routing.redirects 的精确、通配与正则三种匹配模式2 Scalar 如何扩展 OpenAPI 规范：从 x-scalar-environments 到 x-codeSamples 的完整实践指南3 从 Stainless 平滑迁移到 Scalar：一份不改写配置的 SDK 生成迁移实战指南4 Scalar vs Stainless：Stainless 停运后的 SDK 生成器能力对比与迁移承接5 Scalar 视角下的 Stainless SDK 生成器停运：从方案评估到 stainless.yml 兼容迁移的完整指南6 从 Stoplight 迁移到 Scalar：OpenAPI 文档、Markdown 指南与工作流的一站式迁移指南7 Stainless SDK 生成器关停迁移指南：如何用 Scalar 读取 `stainless.yml` 复现你的 API 公开表面8 从 SmartBear API Hub（SwaggerHub）迁移到 Scalar：Design、Portal、Explore 三大模块完整实战指南9 如何从 Swagger UI 迁移到 Scalar API Reference 并映射常见配置项10 Scalar 官方博客总览：从 OpenAPI 工具链到 Agent 时代的技术路线图
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

EIP-7503 零知识虫洞（Zero-Knowledge Wormholes）：为以太坊原生隐私引入的秘密燃烧与再铸造机制Quickwit 缓存架构缺口分析：Parquet 元数据缓存（GAP-007）与多层缓存演进路径SpeechBrain 实战：使用 DNS 嘈杂语音合成器离线生成大规模语音增强训练数据为五种 LoRA 任务定制 Gradio 演示界面：huggingface-lora-space-builder 任务基线 UI 模式实战指南Hindsight Retain 深度解析：如何把对话与文档转化为可检索的结构化记忆Mealie AI 集成完全指南：AI Provider 配置、Import with AI 与提示词定制Bytebot 自托管 AI 桌面 Agent 完全指南：让大模型拥有一台属于自己的电脑Axolotl 集成 Cut Cross Entropy 指南：用低显存交叉熵损失优化大词表模型微调WTF Solidity 链上威胁分析工具全解：交易调试、函数签名解析与反编译实战zstd 在 Linux 内核中的集成与升级全流程：基于 contrib/linux-kernel 的自动化转换指南

项目优选

收起
kernelkernel
deepin linux kernel
C
34
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.21 K
2.81 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
945
1.86 K
docsdocs
暂无描述
Markdown
906
5.84 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
537
607
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
864
1.36 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
4.28 K
1.03 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.39 K
1.48 K
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
550
401
flutter_flutterflutter_flutter
本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本，由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用，3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。
Dart
1.19 K
347