17370845950

本文旨在解决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中通过标签指定远程URL时，Redoc会尝试直接从该URL获取Schema文件。然而，Redoc的客户端JS在发起这个请求时，并不会自动附带任何认证信息（如Authorization头）。这导致服务器因缺少认证而拒绝请求，最终Redoc无法加载并渲染API文档。

例如，以下HTML代码会尝试从远程URL加载Schema：

当https://api.example.com/schema.yaml需要认证时，上述设置将无法正常工作。

解决方案：利用Redocly CLI进行离线文档构建

解决此问题的最有效且推荐的方法是，不依赖Redoc在客户端运行时动态获取Schema，而是通过Redocly CLI工具在构建时预先处理Schema文件，并生成静态HTML文档。这种方法允许您在一个可以访问认证Schema的环境中（例如CI/CD管道、开发机器）完成Schema的获取和文档的生成，然后将最终的静态HTML文件发布。

核心思想

1. 预先获取Schema： 在一个拥有认证凭据的环境中，通过命令行工具（如curl）或脚本，从认证API服务器下载schema.yaml到本地。
2. 本地构建文档： 使用Redocly CLI的build-docs命令，以本地下载的Schema文件为输入，生成完整的HTML文档。
3. 发布静态文档： 将生成的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文档的推荐途径。