本文旨在解决redoc在加载受授权保护的api schema时遇到的挑战。通过详细阐述如何利用redocly cli工具，在本地预先生成完整的api文档html文件，从而规避浏览器端授权请求的限制。这种方法允许开发者在有权限的环境中获取api schema，并将其转换为静态文档，最终实现无缝部署和访问，无需客户端再次进行授权验证。
Redoc与受保护API Schema的挑战
在使用Redoc standalone展示API文档时，如果API schema文件（如schema.yaml）托管在一个需要Authorization头才能访问的私有API服务器上，Redoc默认的客户端请求机制将无法自动包含此授权信息。这意味着，即使页面加载了redoc.standalone.js，尝试通过spec-url属性（例如spec-url='https://api.example.com/schema.yaml'）去获取schema时，请求也会因缺少授权而被服务器拒绝，导致API文档无法正常渲染。
传统的解决方案，如尝试在浏览器端拦截请求并添加授权头，或修改Redoc内部的请求逻辑，通常复杂且不易维护。更优的策略是避免在客户端直接请求受保护的schema，转而采用预处理的方式。
解决方案：利用Redocly CLI进行静态文档生成
Redocly官方提供了一个强大的命令行工具redocly/cli，它允许开发者在本地环境中构建和验证API文档。核心思想是：在拥有访问API schema权限的环境中，先将schema文件下载到本地，然后使用redocly build-docs命令，将本地的schema文件直接编译成一个完整的静态HTML文档。这样生成的HTML文件包含了渲染API文档所需的所有数据和逻辑，无需在客户端运行时再次发起对schema的远程请求。
1. 安装Redocly CLI
首先，确保你的开发环境中安装了Node.js和npm（或yarn）。然后，通过npm全局安装Redocly CLI：
npm install -g @redocly/cli
或者，如果你更喜欢在项目本地安装：
npm install --save-dev @redocly/cli
安装完成后，你可以通过运行redocly --version来验证安装是否成功。
2. 获取API Schema文件
这是关键一步。你需要在一个能够提供Authorization头访问API服务器的环境中，将schema.yaml文件下载到本地。这通常可以通过curl、Postman或其他HTTP客户端工具完成。
示例：使用curl下载受保护的schema
假设你的API服务器在https://api.example.com/schema.yaml提供schema，并且需要一个Bearer Token进行授权：
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" https://api.example.com/schema.yaml -o schema.yaml
请将YOUR_AUTH_TOKEN替换为你的实际授权令牌。执行此命令后，schema.yaml文件将被保存到当前目录下。
3. 构建静态HTML文档
一旦schema.yaml文件在本地可用，你就可以使用redocly build-docs命令来生成静态HTML文档。
redocly build-docs schema.yaml -o index.html
- schema.yaml：这是你刚刚下载到本地的API schema文件。
- -o index.html：指定输出的HTML文件名。你可以根据需要更改此名称。
执行此命令后，redocly/cli会读取schema.yaml文件，并生成一个名为index.html的完整静态HTML文件。这个文件包含了所有渲染API文档所需的JavaScript、CSS和数据，是一个独立的、可直接部署的文档。
4. 部署和发布
现在，你只需将生成的index.html文件（以及可能由Redocly CLI生成的其他相关静态资源，如果你的配置更复杂的话，但对于默认build-docs通常是单个HTML文件）部署到任何静态文件服务器上即可。用户访问这个HTML文件时，将直接看到完整的API文档，而无需浏览器再次向私有API服务器发起请求。
优势与注意事项
- 规避授权问题： 彻底解决了客户端无法携带授权头访问私有API schema的问题。
- 静态部署： 生成的文档是纯静态HTML，可以轻松部署到CDN、GitHub Pages、Netlify等任何静态托管服务，提供快速、可靠的访问。
- 性能优化： 客户端无需等待schema下载，直接加载完整文档，提升用户体验。
- CI/CD集成： 此流程非常适合集成到持续集成/持续部署(CI/CD)管道中。每次API schema更新时，CI/CD系统可以自动下载最新schema，重新构建文档，并部署。
- 版本控制： 将schema文件和生成的文档都纳入版本控制，有助于追踪文档变更。
注意事项：
- 确保你在构建文档时使用的schema.yaml是最新的，以避免文档与实际API不一致。
- 如果你的schema.yaml中包含敏感信息，请确保部署环境的安全性。
- 对于大型API，构建过程可能需要一些时间，但在生产环境中，这种预构建的优势远大于构建时间。
总结
通过采用redocly build-docs命令进行静态文档生成，开发者可以优雅地解决Redoc在展示受授权保护的API schema时遇到的挑战。这种方法不仅简化了部署流程，提高了文档访问的可靠性和性能，还为CI/CD集成提供了便利，是管理和发布私有API文档的推荐实践。
