【亲测免费】 Redoc 使用教程

2026-01-16 10:37:53作者：仰钰奇

Redoc 是一个用于从 OpenAPI 定义自动生成美观 API 文档的开源工具。本教程将指导您了解 Redoc 的项目结构、启动文件以及配置文件。

1. 项目目录结构及介绍

在克隆 https://github.com/Redocly/redoc.git 后，典型的 Redoc 目录结构如下：

.
├── package.json          # 项目依赖和脚本配置
├── README.md              # 项目说明
├── dist                   # 打包后的静态文件输出目录
└── src                    # 主要源代码目录
   ├── index.html          # 入口HTML文件
   └── redoc.standalone.js # Redoc 核心JavaScript库

package.json: 项目的核心配置文件，包含npm依赖和脚本。
README.md: 包含项目的基本信息和指南。
dist: 构建后生成的HTML和资源文件存放位置。
src/index.html: 示例HTML文件，引入Redoc库并展示OpenAPI定义。
src/redoc.standalone.js: Redoc的独立JavaScript库文件。

2. 项目启动文件介绍

Redoc 本身不是一个运行时服务，但可以通过将其HTML和JavaScript库部署到Web服务器上来使用。src/index.html 可以作为示例启动点，它演示了如何集成Redoc到你的页面中。下面是关键部分：

<!DOCTYPE html>
<html lang="en">
<head>
    ...
</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>

这里的 <redoc> 标签指定了OpenAPI规范的位置（spec-url），而<script>标签引入了Redoc库。加载此HTML文件即可看到基于指定OpenAPI描述的API文档。

3. 项目配置文件介绍

Redoc 提供了一些配置选项来定制文档的外观和行为。这些配置是通过在HTML中添加 data-config 属性到 <redoc> 标签来实现的，例如：

<redoc spec-url="http://petstore.swagger.io/v2/swagger.json" data-config='{
    "options": {
        "hideTopLevelTags": true,
        "theme": { "colors": {"primary": {"main": "#007BFF"}}}
    }
}'></redoc>

在这个例子中，data-config 属性包含了JSON对象，定义了隐藏顶级标签(hideTopLevelTags)和自定义主题颜色(theme.colors.primary.main)。完整的配置选项可以在Redoc的官方文档中找到。

更多关于Redoc的详细信息和用法可以访问其官方文档：https://redocly.github.io/redoc/。

redoc

📘 OpenAPI/Swagger-generated API Reference Documentation

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

登录后查看全文