Redocusaurus安装教程：从零开始配置Docusaurus与OpenAPI

Redocusaurus安装教程：从零开始配置Docusaurus与OpenAPI

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

Redocusaurus是一款强大的工具，能够帮助开发者在Docusaurus项目中无缝集成OpenAPI文档。本教程将为您提供从零开始配置Redocusaurus的完整指南，让您轻松搭建专业的API文档网站。

1. 准备工作：搭建Docusaurus项目基础

在开始Redocusaurus的安装配置前，您需要先拥有一个Docusaurus项目。如果您还没有创建Docusaurus项目，可以按照以下步骤进行：

首先，确保您的系统中已经安装了Node.js（建议版本14.0.0或更高）和npm/yarn/pnpm等包管理工具。然后，通过以下命令创建一个新的Docusaurus项目：

npx create-docusaurus@latest my-docusaurus classic cd my-docusaurus

这个命令会创建一个名为my-docusaurus的Docusaurus项目，采用经典模板，为您提供基础的网站结构和功能。

2. 安装Redocusaurus：轻松添加依赖

完成Docusaurus项目的创建后，下一步就是安装Redocusaurus。Redocusaurus提供了多种安装方式，您可以根据自己常用的包管理工具选择合适的命令：

yarn add redocusaurus # OR pnpm add redocusaurus # OR npm i --save redocusaurus

通过上述命令，Redocusaurus及其相关依赖会被自动安装到您的Docusaurus项目中，为后续的配置做好准备。

3. 组织OpenAPI文档：创建规范文件结构

Redocusaurus需要特定的文件结构来存放和管理OpenAPI文档。按照以下步骤创建必要的文件夹和文件：

1. 在Docusaurus项目的根目录下，创建一个名为openapi的文件夹。
2. 在openapi文件夹中，您可以根据需要创建子文件夹来组织不同的API文档。例如，创建一个example子文件夹。
3. 在每个子文件夹中，放置您的OpenAPI规范文件。主文件建议命名为index.openapi.yaml，这样Redocusaurus能够自动识别。

以下是一个推荐的文件结构示例：

├── docs │ ├── ... │ └── ... ├── openapi 🆕 │ └── example 🆕 │ ├── components │ │ └── pets.yaml │ └── index.openapi.yaml ├── docusaurus.config.ts └── package.json

值得注意的是，Redocusaurus支持多文件的OpenAPI规范。在构建时，所有相关文件会通过@redocly/openapi-core自动合并，方便您管理复杂的API文档。

4. 配置Docusaurus：集成Redocusaurus预设

安装完成后，需要在Docusaurus的配置文件中添加Redocusaurus预设。打开项目根目录下的docusaurus.config.ts文件，按照以下步骤进行配置：

首先，在配置文件的开头导入Redocusaurus的类型：

import type * as Redocusaurus from 'redocusaurus';

然后，在presets数组中添加Redocusaurus的配置：

// docusaurus.config.ts const config: Config = { // ...其他配置 presets: [ // ...其他预设配置 [ 'redocusaurus', { openapi: { // 扫描*.openapi.yaml文件的文件夹 path: 'openapi', // 生成页面的公共路由前缀 routeBasePath: '/api', }, specs: [ // 可选：手动提供要加载的文件/URL { // 本地OpenAPI YAML文件的路径 spec: 'api.yaml', id: 'from-manual-file', route: '/api/from-manual-file', }, // 也可以传递OpenAPI规范的URL { spec: 'https://redocly.github.io/redoc/openapi.yaml', id: 'from-remote-file', route: '/api/from-remote-file', }, ], // 修改redoc渲染方式的主题选项 theme: { // 用您的网站颜色更改 primaryColor: '#1890ff', }, }, ] satisfies Redocusaurus.PresetEntry, ], // ...其他配置 };

通过以上配置，Redocusaurus会自动扫描openapi文件夹中的规范文件，并在/api路径下生成对应的API文档页面。如果您指定了specs数组，其中的文件或URL也会在相应的路由下生成文档页面。

5. 自定义Redocusaurus：探索主题和插件选项

Redocusaurus提供了丰富的选项，让您可以根据自己的需求自定义API文档的外观和行为。

5.1 插件选项

插件选项可以传递给specs数组中的对象，主要包括：

• spec（必填）：OpenAPI YAML/JSON文件的路径或远程URL，在构建时会被解析并转发给Redoc组件。
• route（可选）：文档可用的路由URL，将使用docusaurus-theme-redoc中的@theme/ApiDoc主题组件来渲染页面。
• url（可选）：指向OpenAPI规范的URL，用作下载链接。
• layout（可选）：传递给布局的属性对象，用于设置页面的标题、描述等。

5.2 主题选项

主题选项可以传递给theme选项对象，主要包括：

• primaryColor：Redoc使用的突出显示颜色，将作为themes选项中的colors.primary.main，必须是实际的颜色值，而不是CSS变量。
• primaryColorDark：Redoc在暗模式下使用的突出显示颜色，默认为primaryColor。

5.3 Redocly配置文件

如果您的项目文件夹中有redocly.yaml文件，Redocusaurus会自动加载并应用它。您也可以通过config选项提供自定义路径。这个文件可以用来指定主题和其他选项，例如：

# redocly.yaml示例 theme: colors: primary: main: '#1890ff' typography: fontSize: 16px

6. 运行和构建项目：查看API文档效果

完成所有配置后，您可以运行Docusaurus项目来查看API文档的效果：

npm start

这个命令会启动开发服务器，您可以在浏览器中访问http://localhost:3000/api来查看生成的API文档。

需要注意的是，当设置了redocly.yaml配置时，网站可能需要构建后才能正确渲染：

npm run build npm run serve

然后访问http://localhost:3000来查看构建后的效果。

7. 进阶使用：探索更多功能

Redocusaurus还提供了更多高级功能，帮助您创建更丰富的API文档：

• Schema Imports：可以手动引用模式元素，详细内容请参考Schema Imports。
• Operation Imports：可以导入API操作，详细内容请参考Operation Imports。
• 自定义React页面：使用提供的数据和主题组件创建自定义的React页面，满足您特定的需求。

通过这些功能，您可以打造出更加专业、个性化的API文档网站。

总结

通过本教程，您已经了解了如何从零开始安装和配置Redocusaurus，将OpenAPI文档无缝集成到Docusaurus项目中。从准备工作、安装依赖、组织文档结构，到配置Docusaurus、自定义主题和插件选项，再到运行和构建项目，每一步都详细介绍了操作方法。

现在，您可以开始使用Redocusaurus创建自己的API文档网站了。如果您在使用过程中遇到任何问题，可以查阅Redocusaurus的官方文档或相关资源，获取更多帮助和支持。祝您使用愉快！

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