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

登录后查看全文

项目优选

收起

deepin linux kernel

OpenHarmony documentation | OpenHarmony开发者文档

Ascend Extension for PyTorch

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

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

flutter_flutter

ohos_react_native

React Native鸿蒙化仓库

Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用

🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解

cangjie_compiler

仓颉编译器源码及 cjdb 调试工具。