在 Docusaurus 文档站中集成 Redoc 渲染 OpenAPI 接口文档

方案简介

Redocusaurus 是一个把 Redoc 集成进 Docusaurus 站点的开源方案。它的目标用户是既在用 Docusaurus 搭建文档站点，又希望把 OpenAPI 接口参考直接放进同一站点的团队或个人作者。仓库描述明确写到"OpenAPI for Docusaurus with Redoc"，Topics 也涵盖 documentation、docusaurus、openapi、redoc 等关键词，定位非常清晰：让文档与 API 参考共用同一站点的页头页脚。

项目以 monorepo 形式组织，对外发布的是 Redocusaurus 这个 Docusaurus Preset，它把下层的 Docusaurus Theme Redoc 与 Docusaurus Plugin Redoc 组合起来，让用户能"一行配置"就在 Docusaurus 中渲染 OpenAPI 文件或 URL。仓库 README 的 Motivation 一节给出了存在原因："To have the documentation and API reference in the same site with the same headers/footers."——为了把文档与 API 参考放在同一站点、复用同一套页头页脚。

亮点与能力

• Preset 一站式封装：Redocusaurus 自身是一个 Docusaurus Preset，把主题与插件两个包合在一起。
• OpenAPI 文件/URL 生成页面：Plugin Redoc 作为内容插件，可以基于本地 OpenAPI 文件或远程 URL 创建文档页面。
• Redoc 组件渲染：Theme Redoc 包装 RedocStandalone 提供 API 参考的渲染能力。
• 主题样式与 Docusaurus 对齐：Theme Redoc 让 Redoc 与 Docusaurus 主题外观一致。
• Dark Mode 支持：在样式对齐基础上额外提供暗色模式能力。
• 多 OpenAPI spec 示例：仓库内含 Website 子包，使用多种不同 OpenAPI 规范演示 Preset 实际效果。

组成与分工

• Redocusaurus Preset（./packages/redocusaurus）：组合下层 Theme 与 Plugin，对外提供单一接入入口，使用户能"easily add API doc(s) to your docs site"。
• Docusaurus Theme Redoc（./packages/docusaurus-theme-redoc）：包装 RedocStandalone，让 Redoc 视觉与 Docusaurus 主题对齐，并加入 Dark Mode 支持。
• Docusaurus Plugin Redoc（./packages/docusaurus-plugin-redoc）：内容插件，从 OpenAPI 文件或 URL 创建页面，并使用主题中的 Redoc 组件进行渲染。
• Redoc：上游组件库，实际承担 OpenAPI 规范的可视化渲染能力（README 直接给出 GitHub 链接）。
• Docusaurus：上层静态站点框架，提供文档站基础、主题机制与 Preset/Plugin 体系（README 直接给出官网链接）。
• OpenAPI：输入规范，是 Plugin Redoc 的内容源。

前置要求

• 需要已安装 Node.js 与 npm（仓库使用 npm，并提供 npm 版本状态徽章）。
• 需要一个已建好的 Docusaurus 站点作为宿主。
• 需要准备 OpenAPI 规范文件（本地）或可访问的 OpenAPI URL，作为内容源。
• 如需本地开发 Redocusaurus 本身：仓库使用 changesets、eslint、prettier、husky、lint-staged、concurrently、@manypkg/cli 等 monorepo 工具链，需要 Node 环境下安装依赖。

使用与配置要点

• 在 Docusaurus 站点的 docusaurus.config.js 中通过 themes 与 presets 引入 Redocusaurus，即可让站点同时渲染文档与 API 参考。
• 将 OpenAPI 文件放置在项目中或使用远程 URL 作为 Plugin Redoc 的内容来源，Plugin 会基于其创建页面，并由 Theme Redoc 中的 Redoc 组件渲染。
• 日常查阅可通过站点导航切换文档与 API 参考两类页面，二者共享同一套页头页脚，从而达到 README Motivation 中所述目标。
• 验证是否集成成功：在 Docusaurus 站点中能看到与文档同站同头尾的 OpenAPI 渲染页面，并可切换暗色主题。

注意事项与常见问题

• README 自身内容较薄，具体的 Preset/Plugin 配置字段、最小可运行示例需参考其文档站 documentation on the website 与 Examples。
• 关于本方案诞生的背景与历史，README 指向 Docusaurus Issue #638 与作者博客 OpenAPI for Docusaurus。
• 本仓库材料未提供具体的 npm install/npm start 等命令文本，因此本节不杜撰任何命令；如需动手命令，请以上述官方文档为准。
• 若要在本地参与 Redocusaurus 开发，需阅读仓库根目录的 DEVELOPMENT.md 与 CONTRIBUTING.md。

优缺点

• ✓ 主题统一支持暗色模式
• ✓ 同时输出文档与 API 参考
• ✕ 依赖较新 Node 生态
• ✕ 需维护多包 monorepo

出处

本方案挖掘自开源项目 rohit-gohri/redocusaurus，方案内容与实施命令均来自其 README 原文。