写接口的人多少都被文档折磨过。

手写一份 Markdown，接口一改就得同步,改着改着就对不上了。

后来有了 OpenAPI（以前叫 Swagger）这套规范，接口的路径、参数、请求体、响应结构全用一份 YAML 或 JSON 描述清楚,工具能直接读它生成页面,不用再手抄接口表。

规范有了,接下来就是挑个渲染工具把这份 spec 变成能看的网页。

我最早用的是 Swagger UI,最近试了下 ReDoc,集成简单到我有点意外,这里分享一下。

OpenAPI 和 Swagger 先捋清楚

很多人把 OpenAPI 和 Swagger 混着叫,其实得分一下。

OpenAPI 是那套规范本身,现在归 Linux 基金会管,描述一个 REST 接口长啥样。

Swagger 是 SmartBear 家的工具品牌,Swagger UI、Swagger Editor 这些都是它的产品。

简单记:OpenAPI 是“标准”,Swagger 是“一套实现这个标准的工具”。

ReDoc 和 Swagger UI 都是吃 OpenAPI 这份 spec,然后渲染成文档页面。

所以它俩是“同一份输入、不同渲染器”的关系,换工具不用改你的 spec 文件。

ReDoc 最简化集成

先说让我觉得舒服的点:ReDoc 几乎没有接入成本。

你有一份 openapi.yaml(或者 swagger.yaml,叫法无所谓,内容是 OpenAPI 规范就行),然后写个 HTML 页面,body 里塞两行:

<!-- 一个自定义标签,spec-url 指向你的接口定义文件 -->
<redoc spec-url="https://example.com/openapi.yaml"></redoc>

<!-- 引入 ReDoc 的 standalone 打包文件,它会去识别上面那个 redoc 标签并渲染 -->
<script type="module" src="https://cdn.redoc.ly/redoc/v3.x/bundles/redoc.standalone.js"></script>
​

就这样。

浏览器打开这个 HTML,文档页面就出来了。

spec-url 里填你自己的接口文件地址就行,它不光能填线上 URL,也能填本地文件路径。

那个 redoc.standalone.js 是官方 CDN 上的打包版本,v3.x 是取最新的 3.x 版本。

如果不想依赖官方 CDN,也可以用 npm 装到本地,从自己服务器上发出去,官方部署文档里有说明。

整个过程我没碰构建工具,没配 webpack,没装一堆依赖,就一个 HTML + 一个 script 标签。

对我这种“就想把接口文档挂出去看一眼”的需求,这个省心程度刚刚好。

流程大概长这样

一份 spec 到最终页面,中间发生的事其实很直白:

openapi.yaml (OpenAPI 规范文件)
        │
        ↓
redoc.standalone.js  ← 浏览器通过 script 标签加载
        │
        ├─ 读取 <redoc> 标签上的 spec-url
        │
        ↓
拉取并解析 spec
        │
        ↓
渲染成三栏文档页面
 ├─ 左栏:导航菜单
 ├─ 中栏:接口说明正文
 └─ 右栏:请求/响应示例
​

你维护的只有最左边那个 openapi.yaml,后面全是 ReDoc 自动干的。

接口改了,改 spec,刷新页面,文档就更新了。

不用 CDN 还能用 CLI 生成

除了 script 标签这种在线渲染,ReDoc 还有个命令行用法,我觉得挺适合做静态托管。

有 Node 环境的话,一条 npx 命令就能把文档打成一个 HTML 文件:

# build-docs 把 spec 渲染成一个独立的 HTML 文件
# 默认输出名叫 redoc-static.html,直接浏览器打开就能看
npx @redocly/cli build-docs openapi.yaml
​

跑完得到一个 redoc-static.html,一个文件,自带所有东西,丢哪都能看。

这个比在线引 CDN 更适合离线场景或者接口文档要进版本库归档的情况。

跟 Swagger UI 的差异

聊完 ReDoc,回头跟我用惯的 Swagger UI 对比一下。

两者最核心的分歧在一个点上:能不能在页面里直接调接口。

能不能直接试接口

Swagger UI 最大的特色是带一个“Try it out”的交互面板。

你能在文档页面里直接填参数、点发送,真实地把请求打到后端,看返回结果。

它更像一个“接口调试台”,边看文档边调,对联调阶段很友好。

ReDoc 社区版默认是只读的,没有这种直接发请求的调试面板。

它的定位是“把接口文档排得好看、读得清楚”,不是让你在上面调接口。

(ReDoc 的 Try-it 面板是付费的 Redocly 商业版才有的能力,社区版没有。)

页面长相不一样

Swagger UI 是那种可展开/收起的接口列表,一个个接口折叠着,点开看详情。

ReDoc 是经典的三栏布局:左边导航、中间正文、右边放请求响应示例。

读长文档的时候,ReDoc 这种三栏更像在翻一份排版规整的参考手册。

个人感觉 ReDoc 更适合“给人看的对外文档”,Swagger UI 更适合“自己人联调时用”。

集成方式都很轻

这点上两者其实半斤八两,都能用 script 标签直接嵌。

ReDoc 是一个 <redoc> 标签加一个 standalone 脚本。

Swagger UI 也有对应的 dist 包和 CSS,引进来初始化一下即可。

要说 ReDoc 的“最简化”,主要是它连初始化 JS 都省了,属性写在标签上就行。

该怎么选

我自己现在的用法是分场景:

• 对外发布的、给第三方或前端同学当参考的文档 → 用 ReDoc,干净、好读、接入快
• 自己团队内部联调、需要边看边调接口的 → 用 Swagger UI,那个“直接发请求”是刚需
• 想把文档打成一个静态 HTML 归档 → 用 ReDoc 的 build-docs CLI,一条命令搞定

它俩不是二选一的对立关系,毕竟吃的是同一份 OpenAPI spec。

甚至可以两个都挂上:给外人看 ReDoc,给自己留 Swagger UI,spec 文件只维护一份。

还有个小提醒:ReDoc 默认会收集匿名的使用和性能数据(它说不会上传你的接口内容和个人信息)。

介意的话,在 <redoc> 标签上加个 disable-telemetry="true" 关掉就行。

小结

ReDoc 吸引我的点很简单:一份 OpenAPI spec,加一个 script 标签,文档就出来了,几乎零集成成本。

它跟 Swagger UI 的本质差异:

• ReDoc 社区版是漂亮的只读文档
• Swagger UI 是能直接调接口的调试台

两者共用同一份 spec,按场景挑,甚至一起用都行。

如果你也在找个省心的对外接口文档方案,那就引个 redoc.standalone.js 试试吧。