给 OpenAPI 文档配一个能直接发请求的界面（Scalar）

后端接口写完，文档和调试往往落在两个地方：Swagger UI 页面负责看，Postman 或 Insomnia 负责发请求。改一个参数要在两个界面之间来回切，接口一多，文档和实际请求还会对不上。Scalar 针对的就是这个割裂：同一份 OpenAPI 文档，既渲染成给人看的参考页，也能在同一页里直接发请求。

Scalar 是一套用 TypeScript 写的开源 API 平台，读取 OpenAPI/Swagger 文档，渲染成可交互的 API 参考页，并自带一个能直接发请求的 API 客户端。

仓库里主要有两条产品线，一条是 API 参考渲染（api-reference），一条是 API 客户端（api-client），包都放在 packages/ 目录下。客户端有 Windows、MacOS、Linux 三端的桌面安装包，也提供一个浏览器版入口 client.scalar.com。项目 2023-08-16 创建，采用 MIT 许可证，主语言是 TypeScript（占 65.5%），其次是 Vue（29.4%）。仓库地址是 https://github.com/scalar/scalar，目前 16216 Star、943 Fork、37 个开放 Issue。

第一次用它需要知道的事

• 只渲染参考页的话，不需要构建步骤。README 给出的 HTML 方式是从 CDN 加载 ESM 构建，一个 HTML 文件就能跑起来，不用 npm install，也不用打包器。
• 你的 OpenAPI 文档得有一个能访问到的地址。官方示例用的是 https://registry.scalar.com/@scalar/apis/galaxy?format=json。文档地址跨域时，要配置 proxyUrl 走代理，示例里配的是 https://proxy.scalar.com。
• 要改源码或做本地构建，仓库是 pnpm workspace，根目录有 pnpm-workspace.yaml 和 pnpm-lock.yaml。仓库里有 .nvmrc，但 README 节选里没有写具体的 Node 版本号，仓库里也没有说明这一步。
• 仓库体积是 413088 KB，完整克隆比一般前端项目慢，只想用渲染能力的话没必要拉全量源码。
• 客户端分两种形态：桌面版从 scalar.com/download 下载，浏览器版直接用 client.scalar.com，两者都不要求你先装一套后端。

最短上手路径

1. 新建一个 HTML 文件，在 script type="module" 里从 https://cdn.jsdelivr.net/npm/@scalar/api-reference/esm.js 引入 createApiReference。
2. 在 body 里放一个容器节点，例如 <div id="app"></div>。
3. 调用 createApiReference('#app', { url: '你的 OpenAPI 文档地址' })，把 url 换成自己的文档地址。
4. 如果文档在跨域后面，在第二个参数里补上 proxyUrl: 'https://proxy.scalar.com'。
5. 用浏览器打开这个 HTML 文件，参考页会渲染进 #app，端点旁带测试入口，可以直接发请求。

要把文档挂到自己的服务上，README 里建议的路由是 /scalar，套用对应框架的集成后访问这个路径即可。README 还提供了一段可以直接粘给编码 agent 的提示词，让它自己检查项目用的框架、包管理器和路由，再从官方集成列表里挑一个装上。

它实际上能做哪些事

把 OpenAPI 文档变成可交互参考页

• 渲染 OpenAPI/Swagger 文档，页面本身带测试工具，端点上可以直接构造请求。
• 为多种语言和框架生成代码示例，README 把它列为参考页的固有能力之一。
• 提供一份持续增长的框架集成清单，包括 HTML/JS、.NET ASP.NET Core、Aspire、AdonisJS、Astro、Django Ninja、Django、Docker、Docusaurus、Elixir、Express、FastAPI、Fastify、Flask、Go、Hapi、Hono、Java、Laravel Scribe、Laravel、Micronaut、NestJS、Next.js 等。HTML/JS 方式是兜底选项，README 写明它「works everywhere」。

基于 OpenAPI 的 API 客户端

• 免费开源，对 OpenAPI/Swagger 做支持，客户端里带环境变量和动态参数。
• Watch Mode 与服务器框架同步，后端改路由后客户端跟着更新，不用手动导文档。
• 桌面端提供 Windows、MacOS、Linux 安装包，不想装软件可以直接用浏览器版。

文档周边产出

• mock server 相关能力放在 @scalar/blocks 包里。0.4.0 的发布说明提到，mock-server 的 XML 响应改用共享的 schema 感知序列化器，会处理属性、命名空间和根节点命名，发布说明同时提醒已有的 XML 响应快照可能需要更新。
• @scalar/openapi-to-markdown 包负责把文档转成单页 Markdown，1.5.0 版本把单页 Markdown 改得更易读，明确面向读 llms.txt 导出的 AI agent；operation、webhook 或 model 页面现在以该项自身作为 # 标题开头。

参数速查

README 节选里明确出现的渲染配置只有两个字段：url 指向 OpenAPI 文档地址，proxyUrl 用于绕开跨域限制。完整写法如下。

createApiReference('#app', {
  // OpenAPI 文档地址
  url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=json',
  // 避免 CORS 问题
  proxyUrl: 'https://proxy.scalar.com',
})

除这两个字段之外，主题和其余配置项在官方文档里分成 configuration 与 themes 两个页面，仓库 README 节选只给了上面两个字段的示例，其他参数名和取值仓库里没有列出。需要自定义表头或更细的渲染行为时，README 指向了一个 CodePen 示例作为起点。

输出与结果位置

• HTML/JS 方式：渲染结果进你传给 createApiReference 的那个选择器，示例里是 #app，本质是一个前端页面。
• 框架集成方式：文档页作为一条路由挂在现有服务上，README 建议的路径是 /scalar。
• 桌面客户端：从 scalar.com/download 下载安装，浏览器版在 client.scalar.com 直接打开。
• openapi-to-markdown：输出的是 Markdown 文本，适合作为 llms.txt 一类导出供 AI agent 读取。

实际使用中的坑

Issue 列表里最典型的一条是 Vue 组件嵌入外部应用时的 CSS 泄漏：把 <ApiReference /> 按官方 Vue 集成文档放进另一个应用后，样式会溢到宿主页面。这条 Issue 有 17 条评论，状态是待解决，至今仍是开放的。

整数处理也踩过坑。超过 i32 范围的数字（例如 60503861139345408）在客户端里会被处理成异常值，这条 Issue 已经关闭，说明已修复。

路径参数在界面里曾出现编码问题：示例 URL 里的路径参数被编码成 %7Bplatform%7D，参数选择下拉框也跟着消失。这条 Issue 共 19 条评论，已解决。

cookies 一度完全不工作，OAuth 2.0 也被指出功能未完成、缺 PKCE 支持，这两条分别有 31 条和 37 条评论，现状都是已解决。如果你的集成方案依赖认证流程，升级到较新版本再评估，比照着旧版本的行为做判断更靠谱。

替代方案一览

下表里前两个是同功能的同类项目，第三个能解决部分相同的问题。

如果你的工作是每天手动构造一批固定请求，而且这些请求集合要跟着代码仓库走，Bruno 这类以本地文件为核心的桌面客户端更顺手。Scalar 这边，参考页要正常渲染，前提是有一份能被访问到的 OpenAPI 文档地址，文档在跨域后面时还得经过 proxy.scalar.com 做代理转发，比本地客户端多一层外部依赖。你只需要调试、不需要把文档变成网页的话，桌面客户端就够了；反过来，你要的是给已有框架补一个可交互的文档页，Scalar 的集成清单更贴这个场景。

别踩的合规线

API 客户端发出去的是真实请求，会对目标服务产生真实影响。只用它测试你自己拥有的资产，或者已经拿到明确授权的目标。未经授权对第三方服务发起请求，可能违反对方的服务条款；在部分司法辖区，绕过认证或高频探测还可能触及未授权访问相关的法律风险。用同事的线上环境练手、拿别人的公开接口做压测，都属于越线。

代理转发这一环要单独留意。配置 proxyUrl 之后，请求会经过 proxy.scalar.com 这样的第三方服务中转，带 token、Cookie 或内部地址的请求不要走公共代理。认证信息一旦经过第三方节点，就不再受你的网络边界保护。

什么时候值得用它

你手上已经有一份 OpenAPI/Swagger 文档，想要一个比默认文档页更好看、并且能在同一个页面里直接发请求的参考页，Scalar 的 HTML 单文件方式几分钟就能看到效果。

你要给 FastAPI、NestJS、Express、ASP.NET Core 这类框架挂一条文档路由，又不想自己写前端，集成清单里基本能找到对应的一项，省掉从零搭页面的工作量。

你需要一个免费、开源、对 OpenAPI 有一等支持的客户端，桌面端和浏览器端都能用，并且愿意接受它仍在快速迭代、部分能力还在补齐的现状。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。