Redoc静态文档生成：解决受保护API Schema访问问题

本教程旨在解决redoc standalone在加载需要认证的远程api schema时遇到的授权问题。通过介绍`redocly build-docs`命令行工具，我们展示了如何预先下载受保护的api schema并在本地生成静态html文档，从而避免了redoc客户端直接访问带有授权限制的远程资源，实现了文档的离线展示和便捷部署。

Redoc静态文档生成：解决受保护API Schema访问问题

在使用Redoc standalone展示API文档时，一个常见场景是API schema文件（如schema.yaml或openapi.json）托管在需要身份认证的服务器上。Redoc默认通过spec-url属性从远程URL获取schema，但其客户端加载机制通常不包含发送自定义的Authorization头。这导致Redoc无法成功获取受保护的schema文件，从而无法正常渲染API文档。

本文将详细介绍一种推荐的解决方案：利用Redocly CLI工具预先构建静态HTML文档，彻底规避客户端授权问题。

遇到的问题分析

当Redoc standalone通过<redoc spec-url='https://api.example.com/schema.yaml'></redoc>标签尝试加载schema时，它会发起一个HTTP GET请求到指定的URL。如果api.example.com上的schema.yaml需要一个Authorization头（例如Bearer Token），而Redoc的JavaScript运行时没有机制来自动添加这个头，那么请求就会失败，导致API文档无法显示。

直接在浏览器环境中尝试修改Redoc的内部请求逻辑以添加授权头通常是复杂且不推荐的，因为它涉及到深入Redoc的实现细节，并且可能在Redoc更新后失效。

解决方案：使用Redocly CLI预构建文档

解决此问题的最佳实践是利用Redocly CLI提供的build-docs命令。这个方法的核心思想是在文档生成阶段，即在本地或CI/CD环境中，手动获取API schema文件，然后使用Redocly CLI将其编译成静态HTML文档。这样，最终部署的HTML文件就不再需要从远程服务器动态获取schema，从而完全避免了客户端授权的问题。

1. 前提条件

在开始之前，请确保您的系统已安装Node.js和npm（或yarn）。

2. 安装Redocly CLI

首先，您需要全局安装Redocly CLI工具：

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情

npm install -g @redocly/cli

或者使用yarn：

yarn global add @redocly/cli

3. 获取受保护的API Schema文件

这是解决问题的关键步骤。在本地环境中，您可以手动或通过脚本使用适当的授权凭证下载API schema文件。例如，如果您的API需要一个Bearer Token：

# 替换 YOUR_TOKEN 为您的实际授权令牌
# 替换 https://api.example.com/schema.yaml 为您的API schema URL
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/schema.yaml -o schema.yaml

执行此命令后，schema.yaml文件将被下载并保存在当前目录下。

4. 使用Redocly CLI生成静态文档

一旦您有了本地的schema.yaml文件，就可以使用redocly build-docs命令生成静态HTML文档：

redocly build-docs schema.yaml -o index.html

• schema.yaml: 指定本地的API schema文件路径。
• -o index.html: 指定输出的HTML文件名。Redocly CLI会生成一个包含所有必要CSS、JavaScript和API文档内容的独立HTML文件。

5. 部署生成的HTML文档

现在，index.html文件以及可能生成的其他静态资源（如果您的配置需要）已经包含了完整的API文档。您可以将这些文件部署到任何静态文件服务器（如Nginx, Apache, GitHub Pages, Netlify等），用户访问时将直接加载这些静态内容，无需再向API服务器发起schema请求。

优势与注意事项

优势

• 解决授权问题： 彻底避免了Redoc客户端在加载schema时遇到的授权难题。
• 性能提升： 用户访问时直接加载本地静态文件，无需等待远程schema下载和解析，提升了加载速度。
• 离线可用性： 生成的文档可以完全离线访问，无需网络连接即可查看。
• 简化部署： 部署过程变为简单的静态文件托管。
• 版本控制： API schema文件可以纳入版本控制系统，与文档同步管理。

注意事项

• 构建步骤： 这种方法引入了一个构建步骤。每次API schema更新时，都需要重新执行下载和构建命令来更新文档。
• 环境依赖： 需要在构建环境中安装Node.js和Redocly CLI。这在CI/CD流水线中很容易集成。
• 动态内容： 如果您的API schema是极其动态的，且需要实时反映最新状态（这种情况较少见），那么这种静态生成的方式可能需要更频繁的构建。然而，对于大多数API文档而言，这是一个可接受甚至更优的策略。

总结

通过采用redocly build-docs命令预先生成静态API文档，我们有效地解决了Redoc standalone在访问受保护API schema时遇到的授权挑战。这种方法不仅规避了客户端授权的复杂性，还带来了性能提升、离线可用性和简化部署等多重优势，是构建和发布专业API文档的推荐实践。

以上就是Redoc静态文档生成：解决受保护API Schema访问问题的详细内容，更多请关注php中文网其它相关文章！