Redoc：对标 Swagger UI，专注 API 文档展示-马育民老师

# 介绍

**Redoc** 是由 **Redocly** 开发、基于 React 构建的**开源  [OpenAPI](https://www.malaoshi.top/show_1GW3n3vSgjUN.html "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](https://www.malaoshi.top/show_1GW3n3uHkF2M.html "Swagger UI")，是 OpenAPI 文档渲染工具，侧重 **API 文档展示**

### 易混淆说明

Redocly = 公司；
Redoc = 开源免费文档渲染工具；
Redocly CLI = 配套命令行工具；
Redocly Enterprise = 商业付费平台。

# 界面布局（经典三栏结构）

1. **左侧：侧边导航栏**
   - 接口分组、全文搜索、目录折叠
   - 支持自定义标签分组（`x-tagGroups` 扩展）
2. **中间：主体文档区域**
   - 接口简介、路径、请求方式、参数说明、状态码、Markdown描述
   - 嵌套Schema模型可展开/折叠，复杂结构可读性极强
3. **右侧：示例面板**
   - 请求示例(curl、JavaScript、Python等多语言代码片段)
   - 返回Response示例、JSON结构预览

# 特性

### ✅ 优势亮点
1. **超强可读性（最大卖点）**
   并排展示参数、模型、示例，不需要来回切换标签；对多层嵌套JSON Schema、`oneOf/anyOf/allOf` 复杂模型渲染友好，非常适合对外提供开放API文档。
2. **优秀性能，支持超大OpenAPI文件**
   采用**虚拟滚动、按需渲染**，面对上千接口、几MB大小的openapi文件，相比Swagger UI卡顿更少，内存占用更低。
3. **原生响应式布局**
   PC/手机平板自动适配，移动端浏览体验远优于传统Swagger UI。
4. **轻量化部署**
   - 纯前端渲染，**不需要后端服务**；
   - 可打包成**单个独立HTML静态文件**，直接托管在Nginx、GitHub Pages、CDN、对象存储。
5. **高度可定制**
   - 修改主题色、字体、Logo（`x-logo`扩展）
   - 隐藏搜索栏、隐藏下载按钮、禁用代码示例复制
   - 支持Markdown完整语法渲染
6. **丰富扩展支持**
   支持OpenAPI厂商扩展：`x-tagGroups`（分组导航）、`x-logo`、`x-codeSamples` 自定义代码片段等。

### ❌ 主要局限
1. **默认没有「Try it out」在线调试接口功能**
   不能直接在页面发送HTTP请求测试接口（社区有第三方插件可以补充，但原生不支持）。
2. **交互能力弱于Swagger UI**
   主打阅读，不适合开发人员本地调试场景。

### 行业通用最佳实践

**内部开发调试 → Swagger UI**
**对外正式开放文档、客户对接文档 → Redoc**

# Redoc vs Swagger UI 对比

|特性|Redoc|Swagger UI|
|---|---|---|
|核心定位|正式API参考文档（阅读优先）|交互式接口调试工具|
|布局|三栏并排，文档阅读体验优秀|单栏折叠布局|
|Try it在线调试|原生不支持|原生内置|
|大规格文件性能|更好（虚拟滚动）|接口量很大容易卡顿|
|移动端适配|优秀|一般|
|适用场景|对外开发者平台、正式产品文档|后端开发自测、内部联调|

# 应用场景

1. ✅ 面向第三方开发者、合作伙伴开放平台API文档
2. ✅ SaaS产品对外接口参考手册
3. ✅ 接口数量庞大、需要清晰展示复杂JSON模型
4. ✅ 需要静态部署、离线文档、CDN托管
5. ❌ 不适合：需要频繁在线调试接口的内部开发环境（搭配Swagger UI一起使用）

# 生态工具

1. **@redocly/cli**
   不仅打包文档，还支持 OpenAPI 规范校验、文件合并、lint语法检查、版本对比。
   
2. **Redocly Studio**
   在线编写、预览OpenAPI规范（商业版有更多能力）

3. **Redoc Try-it 插件**
   社区扩展，给Redoc增加类似Swagger的在线调试功能。

原文出处：http://www.malaoshi.top/show_1GW3n4ByoyMn.html