本教程旨在解决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工具：
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文档的推荐实践。
