后端用 TypeScript、NestJS 或 Fastify 搭得干干净净,架构清晰、接口类型安全,一切跑得完美。然后有人打开了你的 /docs 端点——还是那个老面孔:Swagger UI。

打开网易新闻 查看精彩图片

Swagger UI 本身没什么可挑的,它服务开发者很多年了。但 API 文档这件事,外观和手感本来可以好得多。Scalar 就是冲着这个来的。

Scalar 是一个开源 API 文档工具,给 OpenAPI 文档套上一层更干净、更现代的界面。用一句话概括:它是 Swagger UI,但开发者体验更好。具体好在哪,可以拆成几层看。

  • 现代界面:布局干净,带暗色模式,主题可自定义。
  • 内置 API 客户端:直接在文档页里测端点,不用切到 Postman。
  • 代码片段:自动生成 JavaScript、Python、Go 等语言的请求示例。
  • 认证支持:兼容 Bearer token、API key 以及其他 OpenAPI 安全方案。
  • OpenAPI 兼容:直接吃你现有的 OpenAPI 规范。

最关键的一点是,你不需要改后端,也不需要重写 API schema。两个工具都能把活干完,区别在于 Scalar 把重心放在整体开发者体验上,尤其是在浏览和测试 API 的时候。

集成成本有多低?如果 Fastify 已经配好 @fastify/swagger,只需要几行。先装包:npm install @scalar/fastify-api-reference,然后在 Fastify 应用里注册,指定 routePrefix 为 /docs、主题设为 purple。打开 http://localhost:3000/docs,现有的 OpenAPI 规范就换上了一套现代文档界面。除 Fastify 外,Scalar 也支持 NestJS、Express、Next.js 等框架。

那要不要把 Swagger UI 换掉?不一定。Swagger UI 仍在积极维护,支持 OpenAPI 3.1、认证和交互式请求。Scalar 提供的只是另一种更精致的浏览与测试体验。对 Swagger UI 满意的话,没有理由着急换;但如果想要更好看、对开发者更友好的文档,又不想费太多力气,Scalar 值得一试。

我们花几个小时打磨后端架构、性能和代码质量,API 文档其实也配得上同样的注意力。一个好的 API,值得一个好的开发者体验。