文档：Redoc架构及应用场景

Posted on Views:

1.Redoc 简介

Redoc是一个开源的OpenAPI/Swagger 文档生成器，专注于美观的 API 文档渲染。

2.核心架构

┌─────────────────────────────────────────────────────
│                  OpenAPI/Swagger Spec               
│              (YAML / JSON 格式)                     
└──────────────────────┬──────────────────────────────
                       │
                       ▼
┌─────────────────────────────────────────────────────
│                   Redoc CLI / Build                  
│   • redoc-cli build spec.yaml --output index.html  
│   • npm/yarn 打包为静态资源                          
└──────────────────────┬──────────────────────────────
                       │
                       ▼
┌─────────────────────────────────────────────────────
│                单页 HTML 输出                         
│  • 自包含 HTML + CSS + JS                            
│  • 无需后端服务，可直接部署到 CDN/Nginx               
└──────────────────────┬──────────────────────────────
                       │
                       ▼
┌─────────────────────────────────────────────────────
│              浏览器端渲染引擎                         
│  • React + Web Components                            
│  • 左侧导航 + 右侧内容区                              
│  • 主题定制（CSS 变量）                               
│  • 搜索/筛选功能                                      
└─────────────────────────────────────────────────────

3.核心特性对比

特性 Redoc SwaggerUI
渲染风格 单页滚动式，层次清晰 标签页式，可在线测试
性能 轻量，加载快 较重型
在线调试 ❌ 不支持 ✅ 支持
自定义主题 ✅ CSS 变量 ⚠️ 有限
侧边栏导航 ✅ 支持 ✅ 支持
OpenAPI 3.x ✅ 完整支持 ✅ 完整支持
部署方式 静态文件 / Docker / CDN 静态文件 / Docker

4.典型应用场景

1. API 文档平台（最常见）

1
2
3
4
5
6
7
8
# docker-compose.yml 示例
services:
  redoc:
    image: redocly/redoc:latest
    ports:
      - "3000:80"
    volumes:
      - ./docs:/usr/share/nginx/html/docs

2. 企业内部 API 网关文档

  • 与 Kong/APISIX 集成，自动生成文档页
  • 支持多版本管理（v1/v2/v3 并行展示）

3. 交付给第三方开发者

  • 生成美观的静态 HTML，嵌入到开发者门户
  • 支持 JWT/OAuth 认证后再访问文档

4. 离线/内网环境

  • 构建为单个 HTML 文件，内网直接分发
  • 无需联网，适合安全要求高的场景

5. CI/CD 自动更新

1
2
3
# GitHub Actions 示例
- name: Build Redoc
  run: npx @redocly/cli build-docs openapi.yaml -o docs/index.html

5.与相关工具对比

工具 定位 适用场景
Redoc 文档渲染 注重美观、静态展示
SwaggerUI 文档+调试 需要在线测试接口
Postman 调试+协作 团队协作、复杂接口测试
Stoplight 设计驱动 API 设计阶段协同
API Platform (ReadMe) 完整平台 商业 SaaS 文档服务

6.推荐架构模式

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  API 服务    │────▶│ OpenAPI 规范 │────▶│  Redoc 渲染  │
│  (Spring/Go) │     │  自动导出    │     │  静态页面    │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                                               ▼
                                      ┌─────────────┐
                                      │  Nginx/CDN  │
                                      │  全球加速    │
                                      └─────────────┘