为什么我们的 Go 后端把 Swagger UI 换成了 Scalar

一个周五下午 4:45，前端工程师在 Slack 发问："为什么 staging 上的 API playground 在往 localhost:8080 发请求？有人把开发服务器开在笔记本上了？"沉默。这个看似无辜的问题暴露了一个秘密：API 文档坏了、过时了、活在另一个宇宙里。这篇 dev.to 文章记录了作者团队在 Go（Fiber）后端把 Swagger UI 换成 Scalar 的全过程。

Swagger 时代的三个痛点

像过去五年里几乎每个 Go 开发者一样，作者团队忠实遵循 Go 仪式：在 handler 函数上方写魔法注释（// @param user_id path string true "User ID"）、跑 swag init 祈祷别漏逗号、把 Swagger UI 挂到 /swagger/*、然后自封"文档冠军"。起初有效，但后端变大后这仪式变成一连串错误喜剧。

文档漂移陷阱。注解以注释形式浮在 handler 上方。你重构了 domain 包里的 Go struct，却忘了更新 handler 上方的 15 行魔法注释。结果：文档声称接口返回纯字符串，Go 代码实际返回嵌套 JSON 对象。前端团队花两小时调试幻影错误，你毫不知情。

2015 时代的 UI 体验。测试 JWT 认证端点、读嵌套 JSON 错误 schema、在 30+ 端点里搜索，都像在用政府税务门户。

硬编码主机噩梦。生成的 spec 把 host: "localhost:8080" 烤死在里面。QA 在 staging（https://staging-api.example.com/docs）测试发布时，每次点 "Try it out" 都静默向 localhost:8080 发 HTTP 请求，然后开始 30 分钟的"在我机器上能跑"争论。

换到 Scalar：单一真源 + 零构建开销

团队不想在 CI 里加一个 50MB 的 npm 构建步骤，也不想在 Go 二进制里嵌复杂静态资源。于是放弃 Swagger UI，换用 Scalar。

激进的一步：不再把注解散落在 40 个 Go 文件里，改用单个 api/openapi/openapi.yaml 文件作为唯一真源。Scalar 是现代零构建 web 组件（@scalar/api-reference），直接从 CDN 加载——不需要 Node.js、不需要 Webpack、没有构建步骤。Go 后端要做的只是提供一个 15 行 HTML 外壳和原始 YAML 文件。

秘密武器：相对路由（url: /api）

治愈 staging 头痛的真正魔法，是把 openapi.yaml 里的完整域名 URL 换成单个相对路径：

servers:
  - url: /api
    description: Same-origin API server

定义 url: /api 后，Scalar 的 HTTP 客户端把测试请求直接挂到当前地址栏的域名上：不需要环境变量、不需要 YAML 模板 hack、staging 上零 CORS 错误——浏览器本来就知道自己在哪。

生产环境锁死：意外访客 404

团队不希望无聊的互联网扫描器在生产环境拿到内部端点的免费交互地图。路由注册时用环境检查把 /docs 只挂载在 dev、test、staging：生产环境访问 GET /docs 得到标准 404。

5 毫秒的验证

为了确保深夜重构不会弄坏路由或把文档泄漏到生产，团队写了快速单元测试：断言非生产环境 /docs 返回 200、断言 openapi.yaml 定义相对 server（url: /api）。两个测试 4ms 通过。

结论

从 Swagger UI 换到 Scalar 带来三个大赢面：零文档漂移（PR 直接审 openapi.yaml，Go handler 注释里的隐藏注解 bug 消失）；零构建开销（Scalar 通过 CDN web 组件在浏览器里跑，无 npm 依赖、无二进制膨胀）；更开心的前端（staging playground 真正能用，UI 是现代开发者工具的观感）。还在跟坏掉的 Swagger playground 或 2015 时代 UI 搏斗的团队，换 Scalar 是一个下午就能拿下的高 ROI 开发者体验改进。

来源：Why We Dumped Swagger UI for Scalar in Our Go Backend - DEV Community