深入解析 ReDoc：从零构建高性能 API 文档的终极指南

最新推荐文章于 2025-03-10 16:40:02 发布
最新推荐文章于 2025-03-10 16:40:02 发布
阅读量1.5k 收藏 30
点赞数 21
文章标签： OpenAPI ReDoc API文档 Swagger 生成 响应式 文档
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/m0_70878103/article/details/145337402
版权

言简意赅的讲解ReDoc解决的痛点

ReDoc 是一个开源的工具，用于将 OpenAPI/Swagger 规范转换为用户友好的 API 文档。相较于传统的 Swagger UI，ReDoc 提供了更专业的外观、更灵活的定制能力，以及更出色的性能，尤其适合大规模 API 文档的展示。

本文将全面讲解如何使用 ReDoc，包括如何书写支持 ReDoc 的 API 文档注解、如何配置 HTML 文件，最后扩展 ReDoc 的更多用法，以帮助开发者更高效地展示 API 文档。

Redoc部署成功展示

为什么选择 ReDoc？

ReDoc 是基于 OpenAPI 规范的静态文档生成工具，以下是其核心特点：

  1. 性能卓越：即使是大型 API 文档，也能快速渲染。
  2. 响应式设计：在桌面和移动设备上都能很好地适配。
  3. 多功能导航：支持嵌套菜单、动态搜索，帮助用户快速找到需要的信息。
  4. 灵活的自定义：支持多种样式和主题设置，轻松适配品牌需求。

使用 ReDoc 构建 API 文档

准备 HTML 页面

下面是一个简单的 HTML 页面，用于展示 ReDoc 的使用方法：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ReDoc 示例</title>
    <!-- 引入 ReDoc 库 -->
    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"></script>
</head>
<body>
    <!-- 创建一个容器，其中 ReDoc 将渲染文档，这个就是swagger的url -->
    <redoc spec-url="https://example.com/api-docs"></redoc>
    <script>
        // 使用 JavaScript 初始化 ReDoc
        Redoc.init('https://example.com/api-docs', {
            scrollYOffset: 50, // 设置滚动偏移量
            theme: {
                colors: {
                    primary: {
                        main: '#ff6f61' // 主颜色
                    },
                    text: {
                        primary: '#333333', // 文字颜色
                    }
                },
                typography: {
                    fontSize: '16px', // 文本字体大小
                    fontFamily: 'Arial, sans-serif', // 文本字体
                }
            }
        });
    </script>
</body>
</html>
代码讲解
  1. ReDoc 库加载：通过 <script> 标签从 CDN 加载 ReDoc。
  2. <redoc> 标签：指定 spec-url 属性为 OpenAPI 文档的 URL，ReDoc 会自动解析并渲染文档。
  3. 自定义配置：
    • scrollYOffset 用于调整页面滚动的偏移量。
    • theme 参数可以自定义文档的颜色和字体样式。

示例：运行环境的配置

将上述代码保存为 index.html，并通过任何静态文件服务器（如 nginx 或 http-server）加载即可。以下是一个简单的本地运行命令：

npx http-server -p 8080

在浏览器中访问 http://localhost:8080/index.html，即可看到渲染好的 API 文档。

编写支持 OpenAPI 的 API 文档

为了让 ReDoc 正确解析 API 文档，我们需要在后端代码中按照 OpenAPI 规范编写注解。例如，以下是一个 Spring Boot 项目的控制器代码示例：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "Home Controller", description = "提供首页相关的接口")
@RestController
public class HomeController {

    @ApiOperation(
            value = "获取首页",
            notes = "返回首页的 HTML 页面。\n\n响应细节未详细说明，因为响应内容为 HTML 页面。"
    )
    @GetMapping("/home")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 500, message = "服务器内部错误")
    })
    public String home() {
        return "<h1>欢迎来到首页</h1>";
    }
}

说明

  1. @Api：描述控制器的用途。
  2. @ApiOperation：提供接口的功能描述和用途说明。
  3. @ApiResponses：定义接口可能返回的状态码及其含义。
  4. @GetMapping：指定接口的 HTTP 方法和路径。
更多注解示例

针对复杂接口，可以进一步扩展：

import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@Api(value = "用户管理", description = "提供用户的增删改查接口")
@RestController
@RequestMapping("/users")
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据用户 ID 获取用户详情")
    @GetMapping("/{id}")
    public String getUser(
            @ApiParam(value = "用户 ID", required = true) @PathVariable Long id) {
        return "用户 ID: " + id;
    }

    @ApiOperation(value = "创建新用户", notes = "创建一个新的用户")
    @PostMapping
    public String createUser(
            @ApiParam(value = "用户名", required = true) @RequestParam String name,
            @ApiParam(value = "用户年龄", required = true) @RequestParam int age) {
        return "创建成功: " + name + ", 年龄: " + age;
    }
}

ReDoc 高级配置

ReDoc 提供了多种配置选项，以满足不同场景的需求。

配置文件方式加载

除了直接在 HTML 中指定 spec-url，还可以通过 JavaScript 动态加载：

fetch('https://example.com/api-docs')
    .then(response => response.json())
    .then(spec => {
        Redoc.init(spec, {
            hideDownloadButton: true, // 隐藏下载按钮
            expandResponses: '200',  // 默认展开所有 200 响应
            theme: {
                colors: {
                    primary: {
                        main: '#007BFF'
                    }
                }
            }
        });
    });

自定义主题

以下是一些常见的主题自定义选项：

  • 隐藏某些文档部分：
Redoc.init('https://example.com/api-docs', {
    hideHostname: true, // 隐藏主机名
    hideInfoSection: true // 隐藏文档信息部分
});
  • 设置文档加载时的默认行为：
Redoc.init('https://example.com/api-docs', {
    expandResponses: 'all', // 默认展开所有响应
    requiredPropsFirst: true, // 在参数列表中优先显示必填字段
});

常见问题与解决方案

  1. 文档加载缓慢：如果文档较大，可以通过优化 OpenAPI 文件结构（如移除冗余字段）提升加载速度。
  2. 跨域问题：确保 API 文档的服务器支持 CORS（跨域资源共享），否则前端无法加载文档。
  3. 样式不符合预期：通过 theme 选项调整配色和排版，或者直接覆盖 ReDoc 的 CSS 样式。

总结

ReDoc 是展示 OpenAPI 文档的强大工具，它不仅美观，而且性能优异。通过本文的讲解，相信你已经学会了如何使用 ReDoc 构建自己的 API 文档，并理解了如何通过注解编写高质量的 API 定义。

通过上述内容，你就已经基本理解了这个方法，基础用法我也都有展示。如果你能融会贯通，我相信你会很强

Best
Wenhao (楠博万)

redoc-demo:ReDoc API文档平台演示
03-18
还原演示 ReDoc API文档平台演示
Redoc 开源项目教程
gitblog_01085的博客
08-09 848
Redoc 开源项目教程 redoc???? OpenAPI/Swagger-generated API Reference Documentation项目地址:https://gitcode.com/gh_mirrors/re/redoc 1. 项目介绍 Redoc 是一个用于从 OpenAPI（前身为 Swagger）定义中生成美观API文档的开放源码工具。它提供了一个响应式的三面板布局：左侧是...
探秘Redoc：优雅地展示你的OpenAPI规范
gitblog_00098的博客
04-17 945
探秘Redoc：优雅地展示你的OpenAPI规范 redoc [NOTE: Project in suspended animation for now] Reversible Reproducible Documents 项目地址: https://gitcod...
Redoc 使用教程
gitblog_00141的博客
08-09 745
Redoc 使用教程 redoc???? OpenAPI/Swagger-generated API Reference Documentation项目地址:https://gitcode.com/gh_mirrors/re/redoc Redoc 是一个用于从 OpenAPI 定义自动生成美观 API 文档的开源工具。本教程将指导您了解 Redoc 的项目结构、启动文件以及配置文件。 1. 项目目...
swagger生成redoc文档
一个天蝎座的程序猿
02-26 8758
一、安装工具 npm install -g redoc-cli 二、生成文档 redoc-cli bundle -o index.html swagger.json { "openapi": "3.0.2", "info": { "title": "Workflow", "description": "API to access AnyShare\r\n\r\n如有任何疑问，可到开发者社区提问：https://developers.aishu.cn\r\n# Authentic
探索智能API文档生成利器: ReDoc
gitblog_00010的博客
03-19 634
探索智能API文档生成利器: ReDoc redoc项目地址:https://gitcode.com/gh_mirrors/red/redoc 是一个开源的、基于OpenAPI规范（前身为Swagger）的现代且美观的API文档生成工具。该项目由Rebilly公司维护，并以MIT许可证开放源代码，旨在让开发者可以轻松地为他们的API创建清晰、易读的文档。 项目简介 ReDoc的主要目标是提供一种...
推荐开源项目：Redoc——优雅的API文档生成器
gitblog_00182的博客
08-09 572
推荐开源项目：Redoc——优雅的API文档生成器 项目地址:https://gitcode.com/gh_mirrors/red/redoc 在当今快速发展的API驱动的世界里，清晰、美观且易于理解的文档是不可或缺的一环。Redoc正是这样一款神器，它基于OpenAPI规范（原Swagger），能够将您的API定义转换为令人眼前一亮的文档。 项目介绍 Redoc是一个开源工具，专注于从OpenA...
开启您的API文档新纪元 —— Redoc：简约之美下的强大功能
gitblog_01097的博客
08-09 597
???? 开启您的API文档新纪元 —— Redoc：简约之美下的强大功能 redoc???? OpenAPI/Swagger-generated API Reference Documentation项目地址:https://gitcode.com/gh_mirrors/re/redoc 在数字化转型的浪潮中，API（应用程序接口）的重要性不言而喻。为了更好地管理和展示API，一款高效且易用的文档生成工...
sample-api-docs:使用OpenAPI，Redocly和GitHub Pages的示例API文档
03-07
样本api文档 使用OpenAPI，Redocly和GitHub Pages的示例API文档
redoc：:blue_book:OpenAPISwagger生成的API参考文档
02-04
OpenAPI / Swagger生成的API参考文档 这是ReDoc（基于React）的2.0版本的README。 1.x版本的自述文件位于分支 产品特点 极其容易的部署 能够将您的文档捆绑到零依赖的HTML文件中 服务器端渲染准备就绪 支持最广泛的OpenAPI v2.0功能（是的，它甚至支持discriminator符） OpenAPI 3.0支持 嵌套对象的整洁交互式文档 代码示例支持（通过供应商扩展） 响应式三面板设计，具有菜单/滚动同步 将API简介集成到侧面菜单中-ReDoc利用了OpenAPI描述字段中的markdown标题。 它将它们拉到侧面菜单中，还支持深度链接。
强大的C#API文档生成工具
07-03
Sandcastle是微软官方的文档生成工具，NDoc开发停止后，这个貌似也是唯一的一个这方面的工具。它从dll文件及其xml注释文件能够生成完整的帮助文档，支持多种生成格式(Helpe1x:chm, Helper2x:Hxs, Website,HelperView),结合新发布的Sandcastle Help File Builder可视化工具，整个生成过程十分简单，而且SHFB工具看起来很强大，不仅能够直接配置生成文档的各个属性，而且还支持很灵活的扩展设置，为我们提供完美的.NET类库文档成为一个可能。
redoc：redoc-从多个项目存储库生成文档
02-04
重做 redoc是一个应用程序，可用于显示来自多个Github存储库的样式化Markdown 。 redoc从GitHub获取内容并 ，缓存HTML以通过目录进行管理，并以主题包进行样式化。 git clone https://github.com/reactioncommerce/redoc.git cd redoc && npm install meteor --settings settings.json 要运行测试： npm run test -运行单元测试npm run test-app “完整应用”测试npm run chimp运行浏览器测试（在应用运行时） npm run
【FastAPI：2023终极指南】：从基础到项目实战，全方位掌握RESTful API开发
![【FastAPI：2023终极指南】：从基础到项目实战，全方位掌握RESTful API开发]...# 1. FastAPI简介与安装配置 FastAPI是一个现代、快速（高性能）的Web框架，用于构建APIs。它基于Python 3.6+类型提示，可以自动地为...
【前后端联调的终极秘诀】：Django与Vue.js无缝对接技巧
首先，我们探讨了前后端联调的重要性，并详细分析了Django后端开发的关键环节，包括模型设计、视图和模板的使用，以及RESTful API的开发。接着，重点阐述了Vue.js前端开发的基础语法、状态管理和路
FastAPI 参数别名与自动文档生成完全指南：从基础到高级实战 [特殊字符]
03-10 848
参数别名是 FastAPI 中用于自定义参数名称的机制，通常用于优化 API 接口的可读性和兼容性。自动文档生成是 FastAPI 中用于自动生成 API 文档的机制，通常通过 Swagger UI 和 ReDoc 实现。通过tags参数，可以自定义文档的标签。
FastAPI 参数别名与自动文档生成完全指南：从基础到高级实战
最新发布
03-10 978
参数别名是 FastAPI 中用于自定义参数名称的机制，通常用于优化 API 接口的可读性和兼容性。自动文档生成是 FastAPI 中用于自动生成 API 文档的机制，通常通过 Swagger UI 和 ReDoc 实现。通过tags参数，可以自定义文档的标签。
了解ReDoc
lmz_lmz的博客
07-20 7536
REDOC - OPENAPI-POWERED DOCUMENTATION UI   伊万·贡查罗夫     我们都喜欢SwaggerUI。这是Swagger / OpenAPI如此受欢迎的原因之一。最近API文档世界出现了一些新的趋势。其中之一是三面板设计文档。竞争的API规范格式有它们，例如API Blueprint有aglio，Postman有Postman Document...
redoc 项目使用教程
gitblog_00008的博客
10-10 1028
redoc 项目使用教程 项目地址:https://gitcode.com/gh_mirrors/redo/redoc 1. 项目介绍 redoc 是一个用于实现 R Markdown 和 Microsoft Word 之间双向转换的 R 包。它能够生成可以反向转换回 R Markdown 的 Word 文档，保留 Word 文档中的编辑内容，包括跟踪的更改。redoc 目前处于暂停状态，但其核心...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值