本文旨在解决redoc standalone在加载需要认证的api schema时遇到的挑战。当api服务器要求`authorization`头才能访问`schema.yaml`时，redoc默认不包含此头，导致加载失败。教程将详细介绍如何通过使用redocly cli进行离线文档构建，预先获取并处理schema文件，从而生成完整的html文档，避免客户端直接请求认证api。
问题背景：Redoc standalone与认证API Schema
在使用Redoc standalone展示API文档时，一个常见场景是API的OpenAPI/Swagger Schema文件（通常是schema.yaml或schema.json）托管在需要认证的API服务器上。默认情况下，当您在HTML中通过<redoc spec-url='https://api.example.com/schema.yaml'></redoc>标签指定远程URL时，Redoc会尝试直接从该URL获取Schema文件。然而，Redoc的客户端JS在发起这个请求时，并不会自动附带任何认证信息（如Authorization头）。这导致服务器因缺少认证而拒绝请求，最终Redoc无法加载并渲染API文档。
例如，以下HTML代码会尝试从远程URL加载Schema：
<html>
<head>
<title>Example API</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='https://api.example.com/schema.yaml'></redoc>
<script src="redoc.standalone.js"></script>
</body>
</html>当https://api.example.com/schema.yaml需要认证时，上述设置将无法正常工作。
解决方案：利用Redocly CLI进行离线文档构建
解决此问题的最有效且推荐的方法是，不依赖Redoc在客户端运行时动态获取Schema，而是通过Redocly CLI工具在构建时预先处理Schema文件，并生成静态HTML文档。这种方法允许您在一个可以访问认证Schema的环境中（例如CI/CD管道、开发机器）完成Schema的获取和文档的生成，然后将最终的静态HTML文件发布。
核心思想
- 预先获取Schema： 在一个拥有认证凭据的环境中，通过命令行工具（如curl）或脚本，从认证API服务器下载schema.yaml到本地。
- 本地构建文档： 使用Redocly CLI的build-docs命令，以本地下载的Schema文件为输入，生成完整的HTML文档。
- 发布静态文档： 将生成的HTML文件部署到任何静态文件服务器上。
实施步骤
1. 安装Redocly CLI
首先，您需要安装Redocly CLI工具。如果您已经安装了Node.js和npm，可以通过以下命令安装：
npm install -g @redocly/cli
2. 获取认证Schema文件
在您的构建环境（或本地开发环境）中，使用适当的工具和认证凭据来下载schema.yaml。例如，如果您的API需要一个Bearer Token：
# 替换 YOUR_AUTH_TOKEN 和 https://api.example.com/schema.yaml curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" -o schema.yaml https://api.example.com/schema.yaml
确保schema.yaml文件已成功下载到您希望构建文档的目录中。
3. 使用Redocly CLI构建文档
一旦Schema文件在本地可用，您就可以使用redocly build-docs命令来生成HTML文档。
# 假设您的schema文件名为 schema.yaml，并且在当前目录下 redocly build-docs schema.yaml --output index.html
- schema.yaml：这是您刚刚下载到本地的Schema文件。
- --output index.html：指定生成的HTML文档的文件名。您可以根据需要更改。
执行此命令后，redocly会读取本地的schema.yaml文件，并将其编译成一个包含Redoc运行时和所有API文档内容的独立HTML文件（index.html）。这个生成的HTML文件是完全独立的，不再需要从远程URL获取Schema。
4. 发布生成的HTML文档
现在，您可以将生成的index.html文件（以及Redocly可能生成的其他静态资源，如CSS/JS文件，如果它们是外部引用的话，但build-docs通常会打包成一个文件）部署到任何静态文件服务器上。用户访问这个HTML文件时，将直接看到完整的API文档，而无需进行任何客户端认证请求。
示例工作流
一个完整的自动化脚本可能看起来像这样：
#!/bin/bash
# 1. 设置认证Token和Schema URL
AUTH_TOKEN="your_secure_authorization_token" # 在实际应用中，这应该从环境变量或安全配置中获取
SCHEMA_URL="https://api.example.com/schema.yaml"
OUTPUT_FILE="api-docs.html"
LOCAL_SCHEMA_FILE="local-schema.yaml"
echo "Downloading schema from ${SCHEMA_URL}..."
# 2. 下载Schema文件，附带Authorization头
curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" -o "${LOCAL_SCHEMA_FILE}" "${SCHEMA_URL}"
# 检查下载是否成功
if [ $? -ne 0 ]; then
echo "Error: Failed to download schema file."
exit 1
fi
if [ ! -f "${LOCAL_SCHEMA_FILE}" ]; then
echo "Error: Schema file not found after download."
exit 1
fi
echo "Schema downloaded to ${LOCAL_SCHEMA_FILE}"
# 3. 使用Redocly CLI构建文档
echo "Building documentation with Redocly CLI..."
redocly build-docs "${LOCAL_SCHEMA_FILE}" --output "${OUTPUT_FILE}"
# 检查构建是否成功
if [ $? -ne 0 ]; then
echo "Error: Failed to build documentation."
exit 1
fi
echo "Documentation built successfully to ${OUTPUT_FILE}"
# 4. 清理本地Schema文件 (可选)
rm "${LOCAL_SCHEMA_FILE}"
echo "Cleaned up local schema file."
echo "Deployment ready: ${OUTPUT_FILE}"优势与注意事项
优势：
- 安全性提升： 避免在客户端浏览器中暴露认证Token，因为Schema的获取是在服务器端或构建环境中完成的。
- 性能优化： 生成的文档是静态HTML，加载速度快，无需额外的网络请求来获取Schema。
- 部署简便： 最终产物是静态文件，可以部署到任何静态文件托管服务，如GitHub Pages, Netlify, CDN等。
- 构建自动化： 易于集成到CI/CD流程中，实现API更新后自动生成和部署文档。
注意事项：
- Schema更新： 如果API Schema频繁变动，您需要确保构建流程能够及时触发，以反映最新的Schema。
- 构建环境： 确保构建环境拥有足够的权限和网络访问能力来获取认证Schema。
- Token管理： 在自动化脚本中，认证Token应妥善管理，避免硬编码，最好通过环境变量或密钥管理服务提供。
总结
当Redoc standalone需要加载受认证保护的API Schema时，直接通过spec-url属性引用远程URL是不可行的。最佳实践是利用Redocly CLI的build-docs命令，在构建时预先获取Schema文件并生成静态HTML文档。这种离线构建的方法不仅解决了认证问题，还带来了安全性、性能和部署便利性等多重优势，是发布专业API文档的推荐途径。
