本教程旨在解决redoc在加载需要认证的api schema时遇到的挑战。当api服务器要求`authorization`头时，redoc默认的客户端请求无法满足。我们将介绍一种通过`redocly build-docs`命令预先生成静态html文档的方法，从而绕过客户端认证限制，实现schema的本地化处理和高效部署。
引言：Redoc与认证API的Schema加载挑战
Redoc是一个流行的OpenAPI（Swagger）文档生成工具，它能够将OpenAPI规范渲染成美观且交互性强的API文档。在典型的使用场景中，用户通过<redoc spec-url='...'></redoc>标签指定一个远程的OpenAPI Schema文件URL，Redoc的JavaScript库会在浏览器端自动发起请求来获取并渲染这个Schema。
然而，当API服务器的Schema文件需要认证才能访问时，例如要求请求头中包含Authorization令牌，Redoc的默认行为就会遇到问题。浏览器发出的请求通常不包含自定义的认证头，导致Schema文件无法正常加载，进而影响文档的显示。用户可能会尝试通过下载Schema文件到本地或寻找在Redoc请求中添加默认认证头的方法，但这些方法往往复杂或不可行。
解决方案：利用redocly build-docs预生成静态文档
解决Redoc在认证API环境下加载Schema问题的最有效方法是，在部署文档之前，预先在有权限的环境中获取Schema文件，并使用Redocly CLI工具将其编译成静态HTML文档。这种方法将Schema获取和文档渲染的过程从客户端浏览器转移到构建阶段，从而完全避免了客户端认证的限制。
Redocly CLI提供了一个强大的命令redocly build-docs，专门用于将OpenAPI定义转换为独立的HTML文件。
核心原理
redocly build-docs命令的工作原理如下：
- 本地化Schema获取： 在构建文档的环境中（例如开发者的本地机器或CI/CD服务器），您可以自由地使用任何工具（如curl、wget或自定义脚本）来获取受保护的OpenAPI Schema文件，因为此时您可以方便地添加所需的Authorization头。
- 静态文件生成： 一旦Schema文件（例如schema.yaml或openapi.json）被下载到本地，redocly build-docs命令会读取这个本地文件，并将其内容与Redoc的渲染逻辑打包成一个完全独立的HTML文件。
- 部署静态HTML： 生成的HTML文件是自包含的，不再需要从远程服务器获取Schema。您可以将其部署到任何静态文件托管服务（如GitHub Pages, Netlify, Nginx等），用户访问时即可直接显示完整的API文档。
实施步骤
以下是使用redocly build-docs解决认证API Schema加载问题的详细步骤：
步骤一：安装Redocly CLI
首先，您需要在您的开发环境中安装Redocly CLI。如果您已经安装了Node.js和npm，可以通过以下命令安装：
npm install -g @redocly/cli
步骤二：获取受保护的OpenAPI Schema文件
在可以访问API服务器并提供认证凭据的环境中，将OpenAPI Schema文件下载到本地。例如，如果您的API需要一个Bearer Token：
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" https://api.example.com/schema.yaml -o schema.yaml
请将YOUR_AUTH_TOKEN替换为实际的认证令牌，并根据您的Schema文件路径调整URL。下载完成后，您将在当前目录得到一个名为schema.yaml（或您指定的其他名称）的本地文件。
步骤三：使用redocly build-docs生成静态HTML文档
有了本地的Schema文件后，运行redocly build-docs命令来生成HTML文档。
redocly build-docs schema.yaml -o index.html
- schema.yaml: 这是您在步骤二中下载的本地OpenAPI Schema文件。
- -o index.html: 指定输出的HTML文件名。您可以根据需要更改文件名。
此命令会处理schema.yaml文件，并生成一个名为index.html的完整静态HTML文件。
步骤四：部署生成的HTML文档
现在，您可以将生成的index.html文件部署到您的Web服务器或静态文件托管服务上。由于该HTML文件已经包含了所有必要的API文档信息，用户访问这个index.html文件时，将直接看到完整的Redoc API文档，而无需浏览器再次向API服务器发起请求。
例如，如果您原先的HTML代码如下：
<html>
<head>
<title>Example API</title>
<meta charset="utf-8"/>
<!-- ... 其他元数据和样式 ... -->
</head>
<body>
<redoc spec-url='https://api.example.com/schema.yaml'></redoc>
<script src="redoc.standalone.js"></script>
</body>
</html>使用redocly build-docs方法后，您将不再需要redoc标签和redoc.standalone.js脚本。生成的index.html文件将是独立的，可以直接作为最终的文档页面。
优势与注意事项
- 绕过认证： 这是最主要的优势，完全解决了客户端无法携带认证头的问题。
- 性能提升： 用户访问文档时无需等待Schema文件从远程服务器加载，文档加载速度更快。
- 离线可用： 生成的文档是完全静态的，可以在没有网络连接的情况下查看（如果所有资源都是本地的）。
- 安全性： 认证令牌只在构建阶段使用，不会暴露在客户端浏览器中。
- 构建自动化： 此过程可以轻松集成到CI/CD流水线中，实现文档的自动化构建和部署。
注意事项：
- Schema更新： 如果您的API Schema经常更新，您需要定期重新执行上述构建步骤，以确保文档是最新的。这可以通过自动化脚本或CI/CD管道实现。
- 本地Schema路径： 确保redocly build-docs命令能够访问到正确的本地Schema文件路径。
总结
通过采用redocly build-docs命令预先生成静态HTML文档，我们能够优雅地解决Redoc在加载需要认证的API Schema时遇到的挑战。这种方法不仅规避了客户端认证的限制，还带来了性能提升、更高的安全性和更灵活的部署选项。对于需要展示受保护API文档的场景，这是一个推荐且专业的解决方案。
