当前位置：首页 > news >正文

Redocusaurus配置完全指南：掌握所有主题和插件选项

news 2026/7/16 22:25:06

Redocusaurus配置完全指南：掌握所有主题和插件选项

【免费下载链接】redocusaurusOpenAPI for Docusaurus with Redoc项目地址: https://gitcode.com/gh_mirrors/re/redocusaurus

Redocusaurus是Docusaurus平台上最强大的OpenAPI文档解决方案，它无缝集成了Redoc来为您的API文档提供专业、美观的展示。这个完整的配置指南将帮助您掌握所有主题和插件选项，让您的API文档网站既美观又实用。😊

为什么选择Redocusaurus？

Redocusaurus让您在Docusaurus站点中轻松添加OpenAPI文档，保持与站点其他部分一致的样式和导航体验。无论是单文件OpenAPI规范还是多文件YAML，Redocusaurus都能完美处理，并提供丰富的自定义选项。

快速安装与基础配置

首先，通过以下命令安装Redocusaurus：

npm install redocusaurus # 或 yarn add redocusaurus

然后在您的docusaurus.config.ts文件中进行基础配置：

import type * as Redocusaurus from 'redocusaurus'; const config = { presets: [ [ 'redocusaurus', { debug: false, specs: [ { id: 'my-api', spec: 'openapi/openapi.yaml', route: '/api/', }, ], theme: { primaryColor: '#1890ff', }, }, ], ], };

插件选项详解

spec（必需选项）

spec参数是配置的核心，支持本地文件路径和远程URL两种方式：

本地文件：spec: 'openapi/openapi.yaml'
远程URL：spec: 'https://api.example.com/openapi.json'

route（路由配置）

定义API文档页面的访问路径：

route: '/api/v1/' // 访问路径为 /api/v1/

layout（页面布局）

自定义页面元数据，提升SEO效果：

layout: { title: 'API文档 - 我的产品', description: '完整的API接口文档和使用指南', keywords: ['API', '文档', 'OpenAPI', 'REST'], image: '/img/api-cover.png', }

url（下载链接）

指定OpenAPI规范的下载链接，用于"下载规范"功能：

url: 'https://raw.githubusercontent.com/your-repo/openapi.yaml'

主题选项深度定制

primaryColor（主色调）

设置文档的高亮颜色，影响链接、按钮和标题：

theme: { primaryColor: '#1890ff', // 亮色模式主色调 primaryColorDark: '#52c41a', // 暗色模式主色调 }

Redocly配置集成

推荐使用redocly.yaml文件进行高级配置：

# redocly.yaml extends: - recommended rules: no-unused-components: error theme: openapi: disableSearch: true theme: colors: primary: main: '#32329f'

然后在配置中引用：

config: path.join(__dirname, 'redocly.yaml'),

多API文档配置

Redocusaurus支持同时展示多个API文档：

specs: [ { id: 'user-api', spec: 'openapi/user-api.yaml', route: '/api/user/', layout: { title: '用户管理API', description: '用户注册、登录、权限管理等接口', }, }, { id: 'product-api', spec: 'openapi/product-api.yaml', route: '/api/product/', layout: { title: '产品管理API', description: '产品创建、查询、更新等接口', }, }, { id: 'external-api', spec: 'https://api.external.com/openapi.json', route: '/api/external/', }, ],

高级主题自定义

自定义Redoc主题

通过packages/docusaurus-theme-redoc/src/redocData.ts文件，您可以深入了解主题配置的内部机制：

theme: { theme: { colors: { primary: { main: '#25c2a0', }, text: { primary: '#242526', secondary: '#5f6368', }, }, typography: { fontSize: '14px', fontFamily: 'system-ui, -apple-system, sans-serif', }, sidebar: { width: '300px', backgroundColor: '#f8f9fa', }, }, }

暗色模式优化

Redocusaurus自动支持暗色模式，但您可以为暗色模式单独配置：

theme: { primaryColor: '#1890ff', // 亮色模式主色 primaryColorDark: '#52c41a', // 暗色模式主色 }

实际配置示例

查看website/docusaurus.config.ts中的完整配置示例：

presets: [ [ 'redocusaurus', { debug: Boolean(process.env.DEBUG || process.env.CI), config: path.join(__dirname, 'redocly.yaml'), openapi: { path: 'openapi', routeBasePath: '/examples', }, specs: [ { id: 'using-remote-url', spec: 'https://redocly.github.io/redoc/openapi.yaml', route: '/examples/using-remote-url/', }, ], theme: { primaryColor: '#1890ff', }, }, ], ]