当redoc需要从受认证保护的远程服务器获取api schema时，直接通过浏览器加载常因缺少authorization头而失败。本教程旨在介绍一种高效解决方案：利用`redocly build-docs`命令预先生成静态html文档。此方法允许在具备认证凭据的环境中获取并处理schema文件，从而避免客户端认证问题，并简化api文档的部署与维护。
理解Redoc与远程Schema加载的挑战
Redoc是一款流行的OpenAPI（Swagger）文档生成工具，它能够将OpenAPI定义渲染成美观且交互式的API文档。通常，Redoc可以通过在HTML页面中指定spec-url属性来加载远程API Schema文件，例如：
Example API
然而，当schema.yaml文件位于需要认证（例如，通过Authorization HTTP头）才能访问的私有API服务器上时，上述直接加载方式会遇到问题。Redoc在浏览器端发起的Schema请求通常不会自动携带所需的认证头，导致请求失败，文档无法正常显示。虽然可以通过一些前端技巧（如拦截请求、修改fetch行为）来尝试添加认证头，但这通常增加了复杂性，且可能存在跨域（CORS）限制。
解决方案：使用Redocly CLI进行离线文档构建
解决Redoc加载受保护远程Schema问题的最佳实践是采用离线构建的方式。Redocly CLI提供了一个强大的build-docs命令，允许你在本地环境中预先生成完整的静态HTML API文档。这种方法的核心优势在于，你可以在文档生成之前，在一个拥有完整认证权限的环境中获取Schema文件。
1. 安装Redocly CLI
首先，你需要全局安装Redocly CLI工具。这通常通过npm或yarn完成：
npm install -g @redocly/cli # 或者 yarn global add @redocly/cli
安装完成后，你可以通过运行redocly --version来验证安装是否成功。
2. 获取API Schema文件
在执行文档构建之前，你需要确保本地拥有最新的API Schema文件（例如schema.yaml或openapi.json）。由于你的Schema服务器需要认证，你可以在一个有权限的环境中，使用curl、wget或其他HTTP客户端工具，并附带必要的Authorization头来下载Schema文件。
例如，如果你的API需要Bearer Token认证：
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" https://api.example.com/schema.yaml -o schema.yaml
请将YOUR_AUTH_TOKEN替换为你的实际认证令牌，并根据实际情况调整URL和输出文件名。
3. 构建静态HTML文档
一旦你成功将schema.yaml文件下载到本地，就可以使用redocly build-docs命令来生成静态文档。该命令会读取本地的Schema文件，并将其渲染成一个独立的HTML文件（通常是index.html），其中包含了Redoc所需的所有样式和脚本。
redocly build-docs ./schema.yaml -o index.html
- ./schema.yaml：指定你本地保存的API Schema文件路径。
- -o index.html：指定输出的HTML文件名。你可以自定义这个名称。
执行此命令后，index.html文件将会在当前目录下生成。这个文件是完全独立的，不依赖于远程的spec-url来获取Schema，因为它已经将Schema内容嵌入或打包到自身内部。
4. 部署与发布
生成的index.html文件是一个纯静态的HTML页面，你可以将其部署到任何静态文件托管服务上，例如GitHub Pages、Netlify、Amazon S3、Nginx等。用户访问这个HTML文件时，将直接看到完整的API文档，无需进行任何额外的网络请求来获取Schema。
优势与注意事项
- 解决认证问题： 这是最直接的优势。由于Schema是在构建时预先获取的，客户端浏览器不再需要处理认证问题。
- 性能提升： 文档加载速度更快，因为所有内容都已打包，减少了浏览器端的网络请求。
- 离线可用性： 生成的文档可以完全离线访问（一旦加载到浏览器中），无需网络连接。
- 简化部署： 静态文件部署简单，易于集成到CI/CD流程中。
- 安全性： 避免在客户端代码中暴露认证逻辑或令牌。
注意事项：
- Schema更新： 当API Schema发生变化时，你需要重新执行下载Schema和构建文档的步骤，以确保部署的文档是最新的。这通常可以通过CI/CD管道自动化。
- 环境依赖： redocly CLI需要Node.js环境。
- 大型Schema文件： 对于非常大的Schema文件，生成的HTML文件可能会比较大，但通常这不会成为主要问题。
总结
通过采用redocly build-docs进行离线文档构建，你不仅能优雅地解决Redoc在加载受认证保护的远程API Schema时遇到的挑战，还能获得性能提升、简化部署和增强安全性的额外益处。这种方法将API文档的生成过程从客户端运行时转移到构建时，使得API文档的维护和发布变得更加高效和可靠。
