介绍
Redoc 是由 Redocly 开发、基于 React 构建的开源 OpenAPI 文档渲染器，专门用来把符合 OpenAPI（Swagger）规范 的 yaml/json 接口定义文件渲染成美观、易读、响应式的在线API参考文档。
- GitHub：https://github.com/Redocly/redoc
- 开源协议：MIT（免费商用）
- 支持规范：OpenAPI 2.0(Swagger2)、OpenAPI 3.0、OpenAPI 3.1
- 定位：偏向「阅读型正式API文档」，而非在线调试工具
一句话理解
类似 Swagger UI，是 OpenAPI 文档渲染工具，侧重 API 文档展示
易混淆说明
Redocly = 公司；
Redoc = 开源免费文档渲染工具；
Redocly CLI = 配套命令行工具；
Redocly Enterprise = 商业付费平台。
界面布局（经典三栏结构）
- 左侧：侧边导航栏
- 接口分组、全文搜索、目录折叠
- 支持自定义标签分组（
x-tagGroups扩展）
- 中间：主体文档区域
- 接口简介、路径、请求方式、参数说明、状态码、Markdown描述
- 嵌套Schema模型可展开/折叠，复杂结构可读性极强
- 右侧：示例面板
- 请求示例(curl、JavaScript、Python等多语言代码片段)
- 返回Response示例、JSON结构预览
特性
✅ 优势亮点
- 超强可读性（最大卖点）
并排展示参数、模型、示例，不需要来回切换标签；对多层嵌套JSON Schema、oneOf/anyOf/allOf复杂模型渲染友好，非常适合对外提供开放API文档。 - 优秀性能，支持超大OpenAPI文件
采用虚拟滚动、按需渲染，面对上千接口、几MB大小的openapi文件，相比Swagger UI卡顿更少，内存占用更低。 - 原生响应式布局
PC/手机平板自动适配，移动端浏览体验远优于传统Swagger UI。 - 轻量化部署
- 纯前端渲染，不需要后端服务；
- 可打包成单个独立HTML静态文件，直接托管在Nginx、GitHub Pages、CDN、对象存储。
- 高度可定制
- 修改主题色、字体、Logo（
x-logo扩展） - 隐藏搜索栏、隐藏下载按钮、禁用代码示例复制
- 支持Markdown完整语法渲染
- 修改主题色、字体、Logo（
- 丰富扩展支持
支持OpenAPI厂商扩展：x-tagGroups（分组导航）、x-logo、x-codeSamples自定义代码片段等。
❌ 主要局限
- 默认没有「Try it out」在线调试接口功能
不能直接在页面发送HTTP请求测试接口（社区有第三方插件可以补充，但原生不支持）。 - 交互能力弱于Swagger UI
主打阅读，不适合开发人员本地调试场景。
行业通用最佳实践
内部开发调试 → Swagger UI
对外正式开放文档、客户对接文档 → Redoc
Redoc vs Swagger UI 对比
| 特性 | Redoc | Swagger UI |
|---|---|---|
| 核心定位 | 正式API参考文档（阅读优先） | 交互式接口调试工具 |
| 布局 | 三栏并排，文档阅读体验优秀 | 单栏折叠布局 |
| Try it在线调试 | 原生不支持 | 原生内置 |
| 大规格文件性能 | 更好（虚拟滚动） | 接口量很大容易卡顿 |
| 移动端适配 | 优秀 | 一般 |
| 适用场景 | 对外开发者平台、正式产品文档 | 后端开发自测、内部联调 |
应用场景
- ✅ 面向第三方开发者、合作伙伴开放平台API文档
- ✅ SaaS产品对外接口参考手册
- ✅ 接口数量庞大、需要清晰展示复杂JSON模型
- ✅ 需要静态部署、离线文档、CDN托管
- ❌ 不适合：需要频繁在线调试接口的内部开发环境（搭配Swagger UI一起使用）
生态工具
@redocly/cli
不仅打包文档，还支持 OpenAPI 规范校验、文件合并、lint语法检查、版本对比。Redocly Studio
在线编写、预览OpenAPI规范（商业版有更多能力）Redoc Try-it 插件
社区扩展，给Redoc增加类似Swagger的在线调试功能。