从 Stoplight 迁移到 Scalar：OpenAPI 文档、Markdown 指南与工作流的一站式迁移指南

本指南以 Scalar 开源 API 平台为基础，面向正在使用（或计划迁出）Stoplight Studio / Stoplight Platform 的 API 团队，完整讲解如何将 OpenAPI 文档、Markdown 指南、Spectral 规则集、自定义域名与旧链接重定向迁移到 Scalar。读完本文，你将掌握从创建 Scalar 项目、接入 Git 仓库、编写 scalar.config.json，到切换域名与配置重定向的完整实操路径，整个过程通常在几小时到几天内即可完成。

为什么从 Stoplight 迁移到 Scalar

Stoplight 曾是 API 文档领域的“挑战者”，以比传统企业方案更清晰的定位著称。在被 SmartBear 收购后，越来越多团队开始寻找现代化的替代品。Scalar 与 Stoplight 在工作流与功能上高度相似，迁移逻辑自然：

1. 都能从 OpenAPI 生成交互式 API 参考文档；
2. 都支持 Markdown 指南；
3. 都兼容 Design-first 与 Code-first 两种 API 工作流；
4. 都内置团队协作能力；
5. 都支持自定义域名、主题与 Logo；
6. 都支持托管部署，或以 Web / React 组件形式嵌入。

在此基础上，Scalar 还提供 Stoplight 已逐渐放弃或缺失的能力：

• 灵活的 SaaS 定价：免费层即可起步，Pro 计划为 150 美元/月并包含 5 个编辑器席位；
• 完全开源、可自托管：Scalar 全量开源，支持自托管部署；
• 内置 API 客户端：Scalar 将 API 客户端直接集成进 API 参考文档，开发者无需离开文档页即可发送测试请求（对应仓库中的 packages/api-client 与 packages/api-reference 两个核心包）。

迁移流程总览

Stoplight 与 Scalar 都在“把 OpenAPI 变成文档”之上叠加了大量功能，但迁移本身并不复杂，整体路径如下：

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

下文先讨论 Scalar 如何融入更大的 API 工作流，再按步骤落地。

Design-first 还是 Code-first：两种工作流都能平滑承接

部分 API 团队通过代码生成 OpenAPI，例如基于代码注解/注释、DSL（如 RSwag），或越来越流行的 OpenAPI-aware 框架。无论使用哪种工具，流程大体一致：生成的文档通过构建脚本或 CI 提交到 Git 仓库，Scalar 可以直接读取这些已提交的 OpenAPI 与 Markdown 内容。

如果生成的 OpenAPI 目前由 Stoplight CLI（不经过 Git） 驱动，那么可以直接替换为 Scalar CLI，将文档推送到 Registry（也可以并行运行一段时间观察效果）。Scalar CLI 的 registry publish 命令支持 --bundle、--treeShake、--version 等选项，详见 documentation/guides/cli/commands.md。当然，也可以借此机会迁移到 Git 工作流——通常来说，把 OpenAPI/Markdown 与源码放在一起维护是最佳实践。

采用 Code-first 工作流的团队，在 Stoplight 侧通常使用 Stoplight Studio（已长期停止维护的桌面版，或 Platform 中的托管编辑器）。Scalar 提供等价的 Editor 界面，可以编辑文档并推送到 Registry，或同步回 Git。Registry 使 OpenAPI 文档对其他工作流工具可用，既能获取最新版本，也能固定到特定版本。

Scalar 的 Editor 界面可用于替代 Stoplight Studio 进行 OpenAPI 编辑。

Step 1：创建免费的 Scalar 账户

Scalar 提供免费层，无需信用卡即可完成大量工作，直接在 Dashboard 注册即可。

Step 2：将你的 OpenAPI 引入 Scalar

Stoplight 曾有多种项目形态：Web Projects、Git Projects、Local Projects。下面统一演示如何转换为 Git Projects，掌握基础后你可以再尝试其他方式。

Git Projects：启用 GitHub Sync

迁移 Stoplight 的 Git Project，本质就是为 Scalar 启用 GitHub Sync。Stoplight 只是在 Git 仓库间推拉，Scalar 同样可以，而且是内置能力，无需额外编写 GitHub Action。

操作路径：进入 Dashboard，点击 Create Documentation，选择 GitHub Sync，从下拉框中选择合适的组织并找到要关联的仓库。

点击目标仓库旁的 Link Repository 链接，会出现 GitHub 仓库设置页面。默认值通常都可以直接使用；如果团队使用特殊分支（如 docs）或版本分支（如 v3）而非 main，在此调整即可。

所有这些配置之后都可以修改，先随意选择并点击发布即可。项目默认是私有的，不必担心未完成的内容被公开。

Web Projects：导出 Stoplight Web 项目

将 OpenAPI 与 Markdown 从 Stoplight 导出，最简单的方式是下载一个包含 OpenAPI 及其他文档的 ZIP 压缩包：进入项目的 studio 页面，点击三行下拉菜单中的 Download project ZIP。

如果只需要 OpenAPI 文档，也可以进入文档页面点击 Export，选择 Bundled 以确保所有 $ref 外部引用都被包含进来。

接下来将这些内容转为 Git Sync 项目，把数据源完全掌握在自己手中：可以新建一个仓库来追踪变更，也可以把下载的 OpenAPI/Markdown 合并进现有源码仓库。无论哪种方式，内容进入仓库后，回到上文“Git Sync”章节，把该仓库接入 Scalar 即可。

Step 3：配置 scalar.config.json

项目接入 Scalar 后，下一步是创建 scalar.config.json 配置文件，在其中声明 OpenAPI 文档的位置与指南（guides）的位置。仓库根目录就有一个真实的示例：scalar.config.json，它同时配置了 subdomain、customDomain 以及大量 siteConfig.routing.redirects 规则，是学习该文件结构的最佳参考。

基础示例：

{
  "$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 的项目设置中，配置自动部署（当分支合并进所选分支时自动发布）。

关于配置文件的更多细节可参考 documentation/guides/docs/configuration/scalar.config.json.md：

• 根属性：$schema（JSON Schema 地址，用于编辑器自动补全与校验）、scalar（配置版本，当前使用 "2.0.0"）、info（项目元信息，如标题与描述）、navigation（导航结构：header 链接、routes、sidebar、tabs）、versions（多版本文档结构）、siteConfig（站点级配置：域名、主题、head、logo）、assetsDir（资源目录，相对于仓库根）。
• 你也可以用 npx @scalar/cli project init 快速生成一个基础配置文件。
• 配置文件默认放在 GitHub 仓库根目录；如需放在其他位置，可在 Scalar Dashboard 中配置路径。
• 若需要在同一域名下部署多个文档项目，可借助 siteConfig.subpath（如 /guides、/api）实现多仓库共用域名。

迁移 Stoplight 的 toc.json 侧边栏

Stoplight 的侧边栏内容位于 toc.json，可以在任意文本编辑器中转换为 Scalar 配置。例如下面这个来自 Stoplight 项目的 toc.json：

{
  "items": [
    {
      "type": "item",
      "title": "Getting Started",
      "uri": "docs/getting-started.md"
    },
    {
      "type": "item",
      "title": "Hello World",
      "uri": "docs/hello-world.md"
    }
  ]
}

把这段 JSON 复制出来，做三处修改：

1. 将 type: item 改为 type: page；
2. 将 uri 改为 filepath；
3. 保留 title 字段。

转换后的 scalar.config.json：

{
  "$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"
          }
        }
      }
    }
  }
}

[!NOTE] 你可以构建更复杂的侧边栏，例如嵌套页面等。仓库根目录的 scalar.config.json 是一个很好的实际示例。

提交该文件并推送。如果已在 Scalar Dashboard 的项目设置中启用自动部署，分支合并后 Deployments 下会出现新条目，届时即可查看效果。

Step 4：审查新文档

点击该部署记录，找到项目文档 URL（形如 https://name-of-your-api.apidocumentation.com），页面会展示两个独立区块：

1. Guides（指南）；
2. 每个 OpenAPI Reference。

包含多个 OpenAPI 文档的项目，会在顶部导航中按 scalar.config.json 中提供的名称逐一展示。点击浏览、确认观感，每个端点上的交互式 API 控制台可以直接发送测试请求。

Step 5：（可选）导出 Spectral 规则集

本步骤仅适用于使用了自定义 Spectral 规则集的团队。Spectral 是 Stoplight 从其他流行 OpenAPI linter 分支出的开源工具，默认会报告 OpenAPI 文档是否合法、是否存在语法错误或无效关键字——如果你在 Stoplight Studio 中看到过 “Missing required keyword” 之类的错误，那就是 Spectral 在起作用。Scalar 支持 Spectral，因此你会在 Scalar Editor 中继续看到相同的错误与警告。

更进一步，Spectral 支持自定义规则集，通常由 API 治理团队构建，用于保证各 API 间的一致性，例如自动化 API 风格指南、推动团队遵循标准或规避不良实践。

迁移托管在 Stoplight Platform 中的自定义 Spectral 规则集：进入 Studio，点击 Export Spectral File 导出。

导出的文件可能只是开关若干规则，也可能定义了自定义规则。请注意：带自定义函数的规则无法正常工作，请直接注释掉这些规则。Scalar CLI 也提供 scalar document lint -r <rule> 命令，可在本地用自定义规则文件对 OpenAPI 进行 lint（见 documentation/guides/cli/commands.md）。

Step 6：（可选）更新自定义域名

当新 API 文档令人满意后，就该把 API 客户端开发者一起带过来了。如果团队有指向 Stoplight 的自定义域名（如 developers.acme.com），可以更新 CNAME 指向 Scalar。

首先，将自定义域名加入 Scalar 配置（详见 documentation/guides/docs/configuration/domains.md）：

// scalar.config.json
{
  "siteConfig": {
    "subdomain": "name-of-your-api",
    "customDomain": "docs.example.com"
  }
  // ...
}

然后在 DNS 中更新 CNAME：将 developers（或你的子域名）从旧的 Stoplight DNS 改为 dns.scalar.com，几分钟后即可生效。

补充几个域名配置要点（源自 domains.md）：

• subdomain 提供免费的 https://<subdomain>.apidocumentation.com 域名，所有 Docs 项目可用；
• customDomain 需要 Scalar Pro，HTTPS 自动启用；
• CNAME 必须为 DNS-only（不经过代理）。若使用 Cloudflare 等提供商，需关闭代理（灰云），因为 Scalar 会为文档执行负载均衡、TLS 终止（HTTP-01 / TLS-ALPN-01）与代理，自定义域名前不能再放置自己的 CDN 或 WAF；
• 根域名（如 example.com）可尝试 ALIAS/ANAME 记录，或联系支持；
• SSL 证书由 Let's Encrypt 自动签发，首次 GET 请求触发；若使用 CAA 记录，需放行 Let's Encrypt；
• 首个以该自定义域名发布且 CNAME 指向 Scalar 的项目即保留该域名，无需 TXT 验证。

Step 7：（可选）添加重定向

如果旧 Stoplight 文档仍有大量流量，可以设置重定向确保既有链接继续可用。Scalar 通过 scalar.config.json 中的 siteConfig.routing.redirects 支持重定向（详见 documentation/guides/docs/configuration/redirects.md）。

如果你之前用自定义域名托管 Stoplight 文档，完成 Step 6 后路径会传递给 Scalar，此时即可用重定向把旧路径指向新路径：

// scalar.config.json
{
  "siteConfig": {
    "routing": {
      "redirects": [{
        "from": "/docs/<stoplight-project>/10a1321b3-:wildcard",
        "to": "/scalar/scalar-registry/github-actions"
      }]
    }
  }
  // ...
}

重定向规则还支持更丰富的匹配方式：

• 通配符："/old-path/:wildcard" → "/new-path"，可匹配任意子路径；
• 带前缀的通配符："/old-path/12345-:wildcard" → "/new-path"；
• 正则："/old-path/:pathMatch(.*)*" → "/new-path"。

仓库根目录的 scalar.config.json 中包含上百条真实的重定向规则（如 /migration/stoplight → /resources/migration/stoplight），展示了大规模迁移时的典型用法。

总结

本次迁移最大的优势在于：Stoplight 与 Scalar 本质上都是基于 OpenAPI 的工具，因此核心规范可以干净地整体迁移，无需重新编写内容或转换为私有格式。

多数团队可在几小时到几天内完成迁移，具体取决于需要搬迁的项目与 API 数量；API 生态较复杂的大型企业耗时稍长。Scalar 团队提供迁移协助与咨询，尤其适合 Stoplight 实现较复杂的团队——该团队包含当初参与构建 Stoplight 的专家，无论项目规模与复杂度如何，都能提供有力支持。