Redoc 开源项目教程

2026-01-16 09:47:43作者：曹令琨Iris

📘 OpenAPI/Swagger-generated API Reference Documentation

项目地址：https://gitcode.com/gh_mirrors/re/redoc

1. 项目介绍

Redoc 是一个用于从 OpenAPI（前身为 Swagger）定义中生成美观API文档的开放源码工具。它提供了一个响应式的三面板布局：左侧是导航菜单和搜索栏，中间显示文档，右侧则展示请求和响应示例。Redoc 支持 OpenAPI 3.0 和 Swagger 2.0 规范，并且可以通过一些扩展定制你的文档样式。

2. 项目快速启动

安装 Redoc CLI

首先确保你的系统安装了 Node.js，然后通过以下命令全局安装 Redoc 的命令行工具：

npm install -g @redocly/cli

生成静态 HTML 文档

如果你有一个 OpenAPI 文件（例如 openapi.yaml），可以使用以下命令快速生成文档：

npx @redocly/cli build-docs openapi.yaml

这将在当前目录下创建一个名为 redoc-static.html 的文件，可以在浏览器中打开查看。

在网页上集成 Redoc

在HTML页面中引入 Redoc 的库文件并设置 spec-url 属性指向你的 OpenAPI 定义：

<!DOCTYPE html>
<html lang="en">
<head>
    <title>我的API文档</title>
</head>
<body>
    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>

将 spec-url 替换为你自己的 OpenAPI JSON 或 YAML 地址。

3. 应用案例和最佳实践

Redoc 被广泛应用于各种组织，包括但不限于 Rebilly, Docker Engine, Zuora, Discourse 等。最佳实践包括：

使用 x-logo 扩展自定义你的品牌标志。
利用 x-tagGroups 建立高级分组以优化侧边栏导航。
提供交互式 "Try it" 控制台以方便测试API。
根据 OpenAPI 定义自动生成代码样本。

4. 典型生态项目

Redoc CLI：用于构建和打包文档的命令行工具，提供额外的 Linting 和 Bundling 功能。
Redocly：Redoc 的商业版本，提供托管的 API 参考文档和更多高级功能。

要了解更多配置和用法，可访问 Redoc 官方文档：https://redocly.github.io/redoc/#configuration。

记得时刻更新 Redoc 版本，以获得最新的特性和改进。祝您使用愉快！

📘 OpenAPI/Swagger-generated API Reference Documentation

项目地址：https://gitcode.com/gh_mirrors/re/redoc

登录后查看全文

项目优选

收起

Ascend Extension for PyTorch

openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。

本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。

Claude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get Started

deepin linux kernel

华为昇腾面向大规模分布式训练的多模态大模型套件，支撑多模态生成、多模态理解。

flutter_flutter

昇腾LLM分布式训练框架

🎉 (RuoYi)官方仓库基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统