如何从 Swagger UI 迁移到 Scalar API Reference 并映射常见配置项

2026-09-14 09:56:43作者：咎竹峻Karen

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

如果你的站点目前用 Swagger UI 渲染 OpenAPI 文档，想换成 Scalar 的 API Reference，同时保留现有 OpenAPI 文档不动，本文给出完整的替换步骤和配置项映射。迁移的前提只有一条：你已经有一个符合 Swagger 2.0、OpenAPI 3.0 或 OpenAPI 3.1 规范的文档（JSON 或 YAML），以及一个当前加载 swagger-ui-bundle.js 的页面。按 Swagger UI 迁移指南的说法，大多数情况下只需几分钟即可完成替换，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>

替换时注意三点：

容器 div 的 id 可以自行选择，它会作为 Scalar.createApiReference() 的第一个参数传入，对应 Swagger UI 的 dom_id。
url 的值直接沿用你现有文档的地址（示例中是 /openapi.json）。
如果你的文档和页面不在同一个源，浏览器会受 CORS 限制。文档给出的解决办法是配置 proxyUrl，例如官方托管代理：

Scalar.createApiReference('#app', {
  url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=json',
  // Avoid CORS issues
  proxyUrl: 'https://proxy.scalar.com',
})

需要注意，自建的代理不能是任意反向代理，必须遵循 Scalar Proxy API，文档提供了一个 Go 语言实现的示例代理。

映射 Swagger UI 常见配置项

迁移文档 documentation/migration/swagger-ui.md 给出了官方配置映射表，逐项对应如下（url、spec、urls、dom_id 四项之外，其余都传入 createApiReference() 的第二个参数对象）：

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`

映射表中几个有默认行为差异的项，在配置文档中的说明如下：

showOperationId 默认 false，而 Swagger UI 里 displayOperationId 默认也是关闭的，行为一致，无需改动。
hideModels 控制 components.schemas（或 Swagger 2.0 的 definitions）是否出现在侧边栏、搜索和内容中，默认 false。
hideTestRequestButton 设为 true 时，认证面板也会一并隐藏，因为它只在 Test Request 可用时才有意义。
persistAuth 默认 false，即认证凭证不写入 local storage。文档对此有安全警告：在浏览器 local storage 中持久化认证信息在部分环境存在风险，需要按自身安全要求决定。

组合起来的完整示例（仅示意，取映射表中的几项）：

Scalar.createApiReference('#app', {
  url: '/openapi.json',
  showOperationId: true,
  expandAllModelSections: true,
  defaultOpenAllTags: true,
  operationsSorter: 'method',
  persistAuth: true,
})

保持 Swagger 风格布局与主题

如果你希望迁移后视觉变化尽量小，Scalar 提供了 classic 布局，文档明确说明它"与传统的 Swagger UI 布局没有太大差别"：

Scalar.createApiReference('#app', {
  url: '/openapi.json',
  layout: 'classic',
})

layout 可选 'modern'（默认）或 'classic'。内置主题包括 default、alternate、moon、purple、solarized、bluePlanet、saturn、kepler、mars、deepSpace、laserwave（配置文档中还列出了 none），通过 theme 字段设置：

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>

版本兼容范围

迁移前确认你的 OpenAPI 文档版本在支持范围内。Scalar 接受 Swagger 2.0、OpenAPI 3.0 和 OpenAPI 3.1 文档（见 OpenAPI 规范说明）。迁移文档的功能对比表给出的支持状态是：

规范版本	Scalar 状态
OpenAPI 3.0 / 3.1 / Swagger 2.0	支持
OpenAPI 3.1.2	支持
OpenAPI 3.2	in progress（尚未完成）

也就是说，文档本身是 Swagger 2.0 或 OpenAPI 3.x 时迁移没有障碍；如果你的文档是 OpenAPI 3.2，需要留意它目前还在适配中。此外，Swagger 2.0 文档的 x-example / x-examples 扩展在 body 参数上同样被支持，这部分功能迁移后不会丢失。

验证迁移结果

替换代码并重新打开文档页后，可以按文档描述的行为逐项确认：

页面渲染出 API Reference 界面，端点、schemas 正常显示（url 指向的文档无需任何修改）。
搜索栏可用——Scalar 的搜索是内置的，不需要 Swagger UI 里那种搜索插件；若想关掉它，用 hideSearch: true。
认证后刷新页面：若设置了 persistAuth: true，认证状态应保留；默认情况下刷新会丢失，这是预期行为而非缺陷。
若页面原来开启了 deepLinking，无需额外配置，Scalar 默认启用。
如果之前用 tryItOutEnabled 控制过测试请求，现在想只读展示，设置 hideTestRequestButton: true 后 Test Request 按钮和认证面板都应消失。

框架集成与边界

如果你的站点不是纯 HTML 页面，而是运行在某个框架里，文档提供了各框架的集成方案（React、Vue、Nuxt、Next.js、Express、Fastify 等），入口在 Getting Started，替换时可按对应框架的集成方式传入同样的配置项。

有几点边界要清楚：

deepLinking、tryItOutEnabled、filter 这几项在 Scalar 中没有对应开关，而是默认行为，迁移后删除即可，不需要寻找等价配置。
proxyUrl、baseServerURL、pathRouting、hiddenClients 等属于 Scalar 的扩展能力，Swagger UI 侧没有对应项，属于可选增强而非迁移必需，按需参考配置文档。
配置文档中 onBeforeRequest 建议通过变更 requestBuilder 来实现请求修改，迁移文档的扩展特性表里有指向其章节的说明，涉及请求拦截逻辑时以配置文档为准。